Merge branch 'fix/src-review-2026-09-24' into main

Fix the critical and required findings of the 2026-09-24 src review
(SPEC.md R-0..R-9.3, 50 tasks). See tasks/plan.md for results and open items.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 12:57:57 +09:00
co-authored by Claude Opus 5.5
123 changed files with 7197 additions and 1001 deletions
+3
View File
@@ -24,3 +24,6 @@ artifacts/tests/visual/
.env
.env.*
!.env.example
# graphify knowledge-graph output (local analysis, not part of the product).
graphify-out/
+103
View File
@@ -0,0 +1,103 @@
# SPEC: src 리뷰(2026-09-24) 긴급·필수 항목 수정
## 목적
`docs/reviews/2026-09-24-src-full-review.md`의 **긴급 1건 + 필수 46건**을 고친다. 권장·사소 항목은 이번 범위가 아니다.
각 요구사항 ID(R-x.y)는 리뷰 문서의 섹션 번호(6.x-y)와 같다. 문제 설명, 근거 코드, 실패 시나리오는 리뷰 문서를 기준으로 한다. 이 문서에는 **무엇이 되면 완료인지**와 **방향이 여러 개인 항목의 결정**만 적는다.
## 범위 밖
- 리뷰의 권장·사소 항목. 단, 같은 코드 줄을 고치다가 자연히 해결되는 경우는 예외다.
- `src/` 밖의 리팩터링. 단, R-0이 요구하는 스크립트와 설정 변경, 그리고 버그를 고정하고 있는 기존 테스트의 수정은 포함한다.
- 공개 포트 시그니처의 파괴적 변경. 추가만 허용한다.
## 공통 완료 기준 (모든 요구사항)
1. 버그를 재현하는 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이는 재현할 수 없는 항목은 fake/fixture로 조건을 만들어 재현한다.
2. `corepack pnpm check:architecture`, `check:types:app`, `check:types:test`, `lint`, `test:unit`, `test:component`이 통과한다.
3. adapter 파일을 추가하거나 이동하면 `docs/reviews/adapters/INVENTORY.md`를 함께 고치고 `check:adapter-inventory`가 통과한다.
4. adapter 간 공용 로직은 `src/adapters/platform/`(kernel)으로, 공유 어휘는 `src/contracts/`로 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
5. 요구사항 하나에 커밋 하나. 커밋 메시지에 R-ID를 적는다.
## 요구사항
### R-0 빌드 기반 (긴급)
- 깨끗한 체크아웃(`src/.generated/` 없음)에서 `dev`, `build`, `check:architecture`, `check:types:app`, `test:unit`, `test:component`, `verify:documentation`이 사전 수동 명령 없이 동작한다.
- CI 게이트도 같은 조건에서 통과한다.
### R-1 browser-transfer
- R-1.1 `dispose()`가 deadline 초과로 실패한 뒤 작업이 끝나면, 다시 호출할 때 store를 닫고 `CLOSED`가 된다.
- R-1.2 opaque ID 문법은 한 곳에서 정의한다. control plane이 받은 ID는 presigned 계층도 받는다.
- R-1.3 동시성 정책 검증은 `partSize × maxConcurrency × copyFactor`를 기준으로 한다. 기본 정책은 이 검증을 통과하고, createSession은 **실제 worker 수**를 요청한다.
- R-1.4 크기나 part 수 한도 초과는 `LIMIT_EXCEEDED`로 보고된다.
### R-2 browser-files / cache-storage / cross-context
- R-2.1 BOUNDED_OBJECT_URL 전략에서 source open이 실패하거나 abort되면 `deliver()`는 reject하지 않고 Result를 반환한다. 늦게 온 lease는 닫힌다.
- R-2.2 source별 sequence watermark는 이벤트 TTL로 지워지지 않는다. 60초 넘게 쉰 뒤의 seq N+1은 `NEXT`다.
- R-2.3 broadcast 발행이 실패해도 수신 listener는 유지된다. broadcast를 받을 수 없는 탭은 `DEGRADED`로 보고된다.
- R-2.4 picker/save picker 함수는 options 객체에 bind되지 않는다. `window` 함수를 그대로 주입해도 동작한다.
- R-2.5 기본 cache 정책이 `Vary: Accept-Encoding` 응답을 받아들인다. `content-type`이 허용 응답 헤더에 없는 정책은 정책 검증에서 거부된다.
### R-3 http / query-cache / auth
- R-3.1 경로 값 `.`과 `..`는 V3와 V2 모두에서 `PATH_VALUE_INVALID`(V2는 `PATH_PARAMETER_INVALID`)로 거부된다.
- R-3.2 세션 알림은 (상태, 주체)가 바뀔 때만 scope fence를 건다. demo 어댑터는 같은 값이면 알리지 않는다. V3의 요청 전 자격증명 없음은 `onUnauthenticated()`를 부르지 않는다. 서버 401만 부른다. **[고위험: 인증·캐시]**
- R-3.3 5xx/408/425 응답의 problem 바디가 유효하지 않으면 HTTP status를 담은 서버 장애로 분류된다. 요청 쪽 위반은 서버 응답 오류(`ENVELOPE_MISMATCH`)로 매핑되지 않는다.
- R-3.4 자격증명 헤더 값은 전송 전에 ByteString(제어문자 없음)으로 검증된다. 실패는 요청 전 단계의 인증 결함으로 분류된다. 대소문자만 다른 중복 헤더는 거부된다. **[고위험: 인증]**
- R-3.5 feature 바인딩에서 `mapSuccess`/`mapProblem`이 던지면 `MAPPING_CONTRACT_VIOLATION` Result로 반환되고 effect가 보존된다.
### R-4 realtime
- R-4.1 `await quiescence` 뒤 DRAINING이면 recovery는 authority를 호출하지 않고 실패한다.
- R-4.2 `retryable:true`인 `PROVIDER_UNAVAILABLE`/`RATE_LIMITED`는 서버 hint가 없어도 재연결 대상이다(reconnect와 polling 모두).
- R-4.3 barrier가 필요 없는 recovery(barrier NONE)는 전송을 닫지 않고 계속된다.
- R-4.4 SSE 파서는 문자마다 인코딩하지 않는다. 250KB chunk 처리가 기존 대비 10배 이상 빨라진다(수동 측정 기록).
### R-5 storage
- R-5.1 orphan 후보 목록은 커서로 이어서 볼 수 있다. 참조 중 청크가 100개를 넘어도 뒤의 orphan이 지워진다. **[고위험: 삭제]**
- R-5.2 dedup으로 재사용한 청크는 grace period 보호를 다시 받는다(mtime 갱신). **[고위험: 삭제]**
- R-5.3 mutation lock 대기 시간은 60초 RPC 타임아웃에 포함되지 않는다. lock 대기는 별도 상한 정책값으로 제한된다.
- R-5.4 파티션 purge는 손상 행이 있어도 끝까지 지운다. 손상은 observe로 보고한다. **[고위험: 삭제]**
- R-5.5 prepared-object 검증은 한 모듈에서 한다. 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증되고, 현재 정책값은 새로 쓰는 데이터에만 적용된다. **[고위험: 데이터 판독]**
### R-6 service-worker / web-push
- R-6.1 확정 이후 메시지(ACCEPTED/RELOAD_REQUIRED)는 `registration.waiting`이 비어도 성공으로 처리된다. 메시지는 nonce/kind로 먼저 거른다.
- R-6.2 drain 요청과 응답은 요청자 빌드와 무관하게 워커 buildId + nonce로 짝을 맞춘다. 다른 빌드 탭이 있어도 활성화가 끝난다.
- R-6.3 앱이 `reloadRequired`/`updateWaiting`을 구독할 수 있다. current 캐시에 없는 asset은 previous 캐시에서 찾는다.
- R-6.4 첫 방문에서 설치 중인 워커는 `ACTIVE`로 보고되지 않는다.
- R-6.5 JavaScript MIME 동의어를 허용한다. `content-encoding`이 있으면 Content-Length와 압축 해제 크기를 비교하지 않는다.
- R-6.6 fetch 핸들러는 manifest에 있는 same-origin GET(비 navigate) 요청에만 `respondWith`를 부른다.
- R-6.7 reconcile에서 서버가 `ABSENT`이면, local association이 ACTIVE였던 경우에만 재등록한다. 그 밖에는 native 구독을 해제한다. **[고위험: 동의]**
### R-7 contracts
- R-7.1 멱등 키는 `^[\x21-\x7E]{1,256}$`만 허용한다. 이 버그를 고정한 기존 테스트도 고친다.
- R-7.2 FEATURE_OVERRIDES의 키(기능 ID)는 설정 이름 금지어 검사 대상이 아니다.
- R-7.3 릴리스 매니페스트 URL은 해석 뒤 origin과 pathname이 입력과 같아야 한다. 탭, 개행, 인코딩된 점 세그먼트는 거부된다.
- R-7.4 REST V2의 COMMAND는 POST/PUT/PATCH/DELETE만 허용된다. `semantics`/`replayPolicy`는 enum으로 검증된다. **[고위험: CSRF]**
- R-7.5 operationId 문법은 contracts 한 곳에서 정의하고 텔레메트리와 진단이 재사용한다. V3가 받는 operationId의 실패 이벤트는 드롭되지 않는다.
### R-8 presentation
- R-8.1 청크 복구 실패 상태는 라우트가 바뀌면 초기화된다. 실패 화면에 "한 번 새로고침" 버튼이 있다.
- R-8.2 WebKit(`Importing a module script failed`)과 Vite CSS preload 실패가 청크 실패로 인식된다.
- R-8.3 선택한 로케일이 preferences에 저장되고 새로고침 뒤에도 유지된다. 세션이 바뀌어도 로케일과 테마는 초기화되지 않는다. unmount 시 router가 dispose된다.
- R-8.4 로케일 변경은 제목과 문구만 갱신한다. 포커스 이동, 스크롤, route 변경 보고는 일어나지 않는다.
- R-8.5 인증필요/잘못된 주소/비활성 기능 화면에서도 제목, 포커스, route 텔레메트리가 동작한다.
- R-8.6 모바일 드로어에서 링크로 이동하면 포커스가 새 페이지(h1/main)로 간다. 메뉴 버튼으로 가지 않는다.
- R-8.7 context 라우트 게이트웨이는 context가 바뀌면 이전 routes로 매칭하지 않는다. 모듈 로드 청크 실패는 `recoverChunk`를 거친다.
- R-8.8 `enabled:false` 쿼리는 로딩으로 표시되지 않는다.
### R-9 bootstrap / platform
- R-9.1 TTL 안에 reload 마커가 있으면 키와 상관없이 자동 reload하지 않는다(세션당 최대 1회). 번갈아 오는 키 테스트를 추가하고, 연속 reload를 기대하던 테스트를 고친다.
- R-9.2 dedup 창 안의 중복 발생 횟수가 수집기로 전달된다.
- R-9.3 리댁션은 문자열 중간의 자격증명, URL 쿼리의 토큰, 이메일을 가린다. 키 목록에 `pwd`, `pass`, `auth`, `otp`, `pin` 계열을 추가한다. **[고위험: 보안]**
## 결정 (방향이 여러 개였던 항목의 기본값)
| ID | 결정 | 이유 |
|---|---|---|
| D-1 (R-0) | 생성 파일을 커밋하지 않는다. 생성 파일을 읽는 진입점(스크립트 또는 package script) 앞에서 생성기를 실행한다. | 6f6c48e가 앱별 생성(`PRODUCT_APP_ID`)을 의도했으므로 gitignore를 유지한다. |
| D-2 (R-1.3) | 기본 `maxConcurrency`를 실제 동작값에 맞춘다. 메모리 한도(`maxInFlightBytes`)는 올리지 않는다. | 지금 기본 동작(동시 1)을 바꾸지 않고, 문서와 코드만 일치시킨다. 다운스트림이 올릴 수 있다. |
| D-3 (R-5.3) | lock 범위는 줄이지 않는다(GC·dedup 정합성). lock 대기만 RPC 타임아웃에서 빼고, 별도 상한을 둔다. | 범위를 줄이면 R-5.2 같은 경합이 새로 생긴다. |
| D-4 (R-2.3) | 발행 쪽 이중 쓰기(broadcast + storage)는 하지 않는다. 수신 유지 + DEGRADED 보고만 한다. | 가장 작은 변경으로 흔한 경로(발행 1회 실패)를 고친다. |
| D-5 (R-8.3) | 로케일 저장은 테마와 같은 `preferences` 경로를 쓴다. Locale/Theme provider는 scope fence 바깥으로 올린다. | 이미 있는 테마 패턴을 재사용한다. |
| D-6 (R-9.2) | 누적 count는 dedup 창이 닫힐 때나 다음 flush 때 요약 이벤트의 `occurrences`로 보낸다. | 기존 이벤트 스키마(`occurrences`)를 그대로 쓴다. |
| D-7 (R-6.3) | previous 캐시 fallback은 hashed URL에만 적용한다. | hashed URL은 같은 URL이면 같은 내용이라 안전하다. |
@@ -31,6 +31,12 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
`allowedResponseHeaderNames`에 `vary`를 포함해야 한다. 아니면 composition이
`TypeError`로 즉시 실패한다. 저장된 variant가 같은 key로 충돌하는 상태를 만들지
않기 위한 cross-field invariant다.
- `allowedResponseHeaderNames`에 `content-type`이 없는 policy도 composition에서
`TypeError`로 실패한다. activation이 저장된 `content-type`을 다시 검증하기
때문이다.
- `Vary: Accept-Encoding`은 policy 없이 항상 허용한다. `Accept-Encoding`은
script가 만든 Request에 들어가지 않는 금지 헤더라 저장과 조회 요청 모두 이
값이 없다. nginx `gzip_vary`와 대부분의 CDN이 이 헤더를 붙인다.
## 1. 변경할 수 없는 복구 원칙
@@ -54,7 +60,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
2. `cache.operation.failed`와 `storage.operation.failed`의 allowlisted
operation/outcome/reason만으로 범위를 좁힌다.
3. runtime status가 `ACTIVE_BROADCAST`, `ACTIVE_STORAGE_FALLBACK`,
`DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지 확인한다.
`DEGRADED_STORAGE_FALLBACK`, `DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지
확인한다. `DEGRADED_STORAGE_FALLBACK`은 BroadcastChannel open에 실패한 tab이다.
다른 tab이 broadcast로만 보낸 event를 받지 못한다.
4. 현재 tab의 mutation 성공 후 local namespace가 stale 처리되는지 확인한다.
5. 다른 tab의 오래된 화면이 단순 stale 표시인지, 실제 server authorization
우회인지 분리한다. authorization 우회는 cache incident가 아니라 P1 security
@@ -70,7 +78,7 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
- `BROADCAST_PUBLISH_FAILED`
- `STORAGE_LISTENER_FAILED`
- `STORAGE_PUBLISH_FAILED`
- runtime status `DEGRADED_LOCAL_ONLY`
- runtime status `DEGRADED_STORAGE_FALLBACK` 또는 `DEGRADED_LOCAL_ONLY`
### 확인
+827
View File
@@ -0,0 +1,827 @@
# src/ 전체 코드 리뷰
> 검토일: 2026-09-24
>
> 검토 기준: `main` / `e59994a`
>
> 검토 범위: `src/` 전체 (diff 리뷰 아님). 약 8.7만 줄, 9개 영역
>
> 검토 관점: 정확성, 보안, 성능, 구조(중복·경계·파일 크기), 테스트 공백
>
> 판정: **NEEDS_FIX**
>
> 이 문서는 리뷰 결과 기록이다. 이 리뷰에서 코드는 수정하지 않았다.
## 1. 결론
레이어 규칙과 입력 경계 검증은 전반적으로 잘 지켜져 있다. presentation이 adapter를 직접 import하는 곳이 없고, 신뢰할 수 없는 입력은 크기 상한과 정확한 키 검사를 거친 뒤에 파싱한다.
문제는 세 가지로 모인다.
1. **깨끗한 체크아웃에서 게이트가 깨진다.** 생성 파일을 만드는 단계가 dev/build/test/CI 어디에도 없다.
2. **버그가 모듈과 모듈이 이어지는 지점에 몰려 있다.** 모듈 하나하나는 테스트가 있지만, 연결 부분은 테스트가 없다.
3. **같은 로직이 여러 벌로 복사되어 규칙이 서로 다르다.** 한 곳을 고쳐도 다른 복사본은 그대로 남는다.
## 2. 검토 방법과 표기
```text
src/ 8.7만 줄 → 9개 영역으로 분할 → 리뷰 에이전트 9개가 병렬로 읽음
→ 오케스트레이터가 주요 12건을 코드에서 직접 재확인 → 게이트 직접 실행
```
| 영역 | 경로 | 규모 |
|---|---|---|
| 1 | `src/adapters/browser-transfer/` | 약 12.8k줄 |
| 2 | `src/adapters/browser-files/`, `cache-storage/`, `cross-context-invalidation/` | 약 8k줄 |
| 3 | `src/adapters/http/`, `browser-rpc/`, `query-cache/`, `auth/`, `diagnostics/`, `telemetry/` | 약 8.2k줄 |
| 4 | `src/adapters/realtime/` | 약 10.3k줄 |
| 5 | `src/adapters/storage/`, `platform/`, `browser-file-storage/` | 약 14.9k줄 |
| 6 | `src/adapters/web-push/`, `service-worker/` | 약 5.9k줄 |
| 7 | `src/contracts/` | 약 8.3k줄 |
| 8 | `src/presentation/` | 약 7.8k줄 |
| 9 | `src/application/`, `features/`, `bootstrap/`, `platform/`, `apps/`, `contexts/` | 약 10.6k줄 |
리뷰 전제 (소유자 결정, `refactor-direction-decisions` 참조):
- 이 레포는 템플릿이다. 레포 안에서 쓰는 곳이 없는 코드나 빈 레지스트리는 다운스트림용 seam이므로 "죽은 코드"로 보지 않았다. 다만 갈라진 중복 복사본은 문제로 봤다.
- adapter 배럴(`index.ts`)은 공개 경계다.
- adapter는 다른 concrete adapter를 import할 수 없다. 예외는 `src/adapters/platform/`(폴더 전체), `src/adapters/browser-file-storage/result.ts`, `src/adapters/cross-context-invalidation/index.ts`다.
표기:
- **심각도**: 긴급(데이터 손실·보안 구멍·기능 고장) / 필수(실제 버그 또는 고쳐야 할 구조 문제) / 권장 / 사소
- **확신도**: 확인됨(코드 경로를 따라가 반드시 일어남을 확인) / 가능성(조건에 따라 일어남. 확인 방법을 적음)
- **✓ 재확인**: 오케스트레이터가 코드를 직접 다시 읽어 확인한 항목. 나머지는 에이전트 보고이고, 일부는 에이전트가 레포 밖 scratchpad의 node 스크립트로 재현했다.
## 3. 게이트 실행 결과
깨끗한 체크아웃(`e59994a`, `src/.generated/` 없음):
| 게이트 | 결과 |
|---|---|
| `corepack pnpm check:architecture` | 실패 — `ERR_MODULE_NOT_FOUND: src/.generated/product-feature-index.ts` |
| `corepack pnpm check:types:app` | 실패 — TS 에러 20개 |
| `corepack pnpm lint` | 통과 |
| `corepack pnpm test:unit` | 실패 — 131개 파일 중 18개 실패 |
| `corepack pnpm test:component` | 실패 — 25개 파일 중 13개 실패 |
| `corepack pnpm verify:documentation` | 실패 — 같은 `ERR_MODULE_NOT_FOUND` |
`node scripts/generate-product-feature-index.ts` 실행 후:
| 게이트 | 결과 |
|---|---|
| `check:architecture` | 통과 |
| `check:types:app` | 통과 |
| `test:unit` | 통과 — 1779/1779 |
| `test:component` | 통과 — 132/132 |
| `verify:documentation` | `PASS_SCOPED` |
생성한 `src/.generated/`는 확인 뒤 다시 지웠다. `dev`와 `build`는 실행하지 않았다. 두 명령 모두 같은 import를 거치므로 실패할 것으로 보인다.
## 4. 먼저 고칠 것
| 순위 | 항목 | 위치 | 섹션 |
|---|---|---|---|
| 1 | 깨끗한 체크아웃에서 게이트 실패 | `src/features/installed-product-manifest.ts:4` | 6.0 |
| 2 | 경로 값 `..`가 다른 엔드포인트로 요청을 보냄 | `src/adapters/http/http-contract-bridge.ts:191` | 6.3-1 |
| 3 | 로그아웃 해제 실패 뒤 새 계정이 opt-in 없이 push 등록됨 | `src/adapters/web-push/push-subscription-adapter.ts:345` | 6.6-7 |
| 4 | 파티션 purge가 손상 행 1개에 영구히 막힘 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts:2584` | 6.5-4 |
| 5 | 멱등 키 앞뒤 공백이 잘려 두 명령이 같은 키가 됨 | `src/contracts/mutation-intent.ts:34` | 6.7-1 |
| 6 | 롤링 배포 중 부트 reload 무한 반복 | `src/platform/release/release-mismatch-recovery.ts:59` | 6.9-1 |
| 7 | 킬스위치 기능 ID에 금지어가 있으면 부팅 실패 | `src/contracts/env.ts:80` | 6.7-2 |
| 8 | WS/SSE가 네트워크 끊김·서버 재시작 뒤 재연결 안 함 | `src/adapters/realtime/reconnect-coordinator.ts:1661` | 6.4-2 |
| 9 | 빌드가 다른 탭이 있으면 SW 활성화가 항상 30초 타임아웃 | `src/adapters/service-worker/service-worker-lifecycle.ts:368` | 6.6-2 |
| 10 | 세션 알림마다 캐시 전체 비움 + 앱 트리 remount | `src/adapters/query-cache/server-state-scope-runtime.ts:90` | 6.3-2, 6.8-3 |
## 5. 영역을 가로지르는 패턴
### 5.1 갈라진 복사본
같은 개념이 여러 벌 구현되어 있고 규칙이 서로 다르다. 한 벌만 고치면 나머지는 그대로 남는다.
| 개념 | 복사본 위치 | 차이 |
|---|---|---|
| abort/timeout race | browser-files(`download-delivery-adapter.ts:1032`, `browser-file-vault.ts:872`), realtime 6곳, browser-transfer runtime(`resumable-upload-runtime.ts:1299`) | kernel `src/adapters/platform/abortable-operation.ts`의 `createAbortableOperation`을 쓰지 않음. 일부는 늦게 도착한 자원을 닫지 않음 |
| opaque ID 정규식 | `resumable-upload/checkpoint-schema.ts:11`, `presigned/*`, web-push 3곳 | 첫 글자·길이 규칙이 다름 |
| exact-key 스냅샷 | contracts 6곳(`exact-snapshot.ts:66`, `read-only-registry.ts:54`, `browser-rpc.ts:399`, `realtime-streams.ts:529`, `cache-invalidation.ts:208`, `service-worker-static-manifest.ts:98`), realtime 3곳, web-push | enumerable·getter·Proxy 처리 수준이 다름. 두 곳은 우회 가능 |
| IndexedDB 저장 행 검증 | `indexeddb-runtime.ts`, `indexeddb-maintenance.ts`, `indexeddb-governance.ts` | 필드 추가 시 한쪽만 고치면 정상 행이 손상으로 판정됨 |
| OPFS prepared-object 검증 | worker, journal, client | 정책 변경 시 기존 객체가 읽히지 않음 |
| 텔레메트리 전송기 | `src/adapters/telemetry/best-effort-telemetry.ts`, `feature-telemetry.ts`, `src/platform/telemetry/telemetry-pipeline.ts` | rate limit 합산 40/분, credentials 설정·body 스키마가 다름 |
| "한 번만 reload" 가드 | `src/application/use-cases/decide-chunk-recovery.ts`, `src/platform/release/release-mismatch-recovery.ts` | 키 형식·TTL·마커 삭제 규칙이 다름 |
| operationId 형식 | `telemetry.ts:111`, `external-contract-runtime.ts:237`, `api-operations.ts:54`, `browser-rpc.ts:185` | 텔레메트리 규칙이 가장 엄격해서 실패 이벤트가 드롭됨 |
| 자격증명 헤더 검증 | `http-contract-bridge.ts:83`, `http-execution-v3.ts:1100`, `auth/external-session-adapter.ts:37` | CR/LF만 막음. 길이를 UTF-16과 UTF-8로 따로 셈 |
수렴할 곳은 이미 있다. adapter 공용 로직은 `src/adapters/platform/`(규칙 변경 불필요), 공유 어휘는 `src/contracts/exact-snapshot.ts`와 `read-only-registry.ts`다.
### 5.2 테스트가 없는 연결 지점
모듈 단위 테스트는 각자의 동작을 고정한다. 그런데 연결된 두 모듈이 서로 다른 약속을 하고 있다.
- 전송 계층 ↔ reconnect: 전송은 `PROVIDER_UNAVAILABLE retryable:true`를 보내는데 reconnect는 이를 종료로 처리한다 (6.4-2).
- event consumer ↔ stream coordinator ↔ 전송: barrier NONE 스트림이 recovery 한 번에 종료된다 (6.4-3).
- SW page controller ↔ worker: drain 요청과 응답의 필터가 서로 맞지 않는다 (6.6-1, 6.6-2).
- 세션 알림 ↔ scope fence ↔ presentation 트리: 알림마다 캐시 비움과 remount가 일어난다 (6.3-2, 6.8-3).
- cross-tab 수신 ↔ query-cache coordinator: GAP이 전체 무효화로 이어진다 (6.2-2).
### 5.3 텔레메트리
영역 3과 9에서 같이 나왔다. occurrences가 항상 1이다 (6.9-2). 리댁션이 문자열 시작 부분만 검사한다 (6.9-3). camelCase operationId의 API 실패 이벤트가 드롭된다 (6.7-5). best-effort fetch에는 타임아웃이 없다 (6.3-10).
## 6. 영역별 발견
### 6.0 공통 — 깨끗한 체크아웃에서 게이트 실패
**[긴급·확인됨 ✓]**
- 위치: `src/features/installed-product-manifest.ts:4`
- 문제: 이 파일이 `../.generated/product-feature-index.ts`를 import한다. `.gitignore:4`가 `.generated/`를 제외하므로 이 파일은 커밋되지 않는다. 생성 명령은 `generate:feature-index`(`scripts/generate-product-feature-index.ts`)인데, `dev`/`build`(`scripts/build-frontend.ts`)/`check:*`/`test:*` 스크립트, `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, README 어디에도 이 명령을 먼저 실행하는 단계가 없다.
- 시나리오: 레포를 새로 clone한 사람이나 CI는 아키텍처 검사, 타입체크, 단위·컴포넌트 테스트를 모두 실패한다(3장 참조).
- 도입 시점: `6f6c48e`(도메인 확장 리팩터링).
- 수정 방향: `generate:feature-index`를 `pre*` 스크립트나 각 게이트 앞에 붙이고, CI 게이트에 `check:feature-index`를 추가한다. 또는 생성물을 커밋하고 `check:feature-index`로 최신 여부만 검사한다.
### 6.1 browser-transfer (`src/adapters/browser-transfer/`)
요약: 보안 경계는 탄탄하다(vault 식별자, 1회용 replay guard, redirect/credential 차단, 스트리밍 SHA-256, 이미지 헤더 bounds check). 결함은 resumable upload의 수명 관리, 정책 처리, 실패 분류, 그리고 계층 간 ID 규칙 불일치에 몰려 있다.
1. **[필수·확인됨 ✓] `dispose()` 결과가 캐시되어 한 번 실패하면 영구히 CLOSING**
- 위치: `resumable-upload/resumable-upload-runtime.ts:331`, `:363-369`
- 문제: `drain ??= (async () => …)()`가 cleanup deadline을 넘기면 `UNAVAILABLE, retryable:true`를 반환하고 그 promise를 계속 들고 있다. 뒤에서 `quiescent`가 결국 `"DRAINED"`가 되어도 기다리는 쪽이 없다. 그래서 `checkpoints.close()`와 `lifecycle = "CLOSED"`가 실행되지 않는다.
- 시나리오: provider가 느려 첫 `dispose()`가 EXPIRED로 끝남 → 몇 초 뒤 작업은 모두 끝남 → 호출자가 retryable을 믿고 다시 `dispose()` → 같은 실패가 그대로 돌아옴. IDB 연결도 열린 채 남는다.
- 수정 방향: EXPIRED일 때 `drain = null`로 되돌리거나, `quiescent.then`으로 늦게라도 store를 닫고 CLOSED로 전환한다.
- 테스트: `tests/unit/resumable-upload-runtime-teardown.test.ts`는 첫 실패만 확인한다. 재호출 시나리오는 없다.
2. **[필수·불일치는 확인됨, 실제 발생은 가능성] opaque ID 문법이 계층마다 다름**
- 위치: `resumable-upload/checkpoint-schema.ts:11`, `presigned/presigned-capability-http-provider.ts:38`, `:380-383`, `presigned/presigned-transfer-executor.ts:1213-1223`
- 문제: control plane은 `/^[A-Za-z0-9_-]{8,512}$/`를 받고, presigned 계층은 `/^[a-z0-9][a-z0-9._:-]{0,255}$/i`로 다시 검사한다. presigned 쪽은 `-`/`_`로 시작하는 ID와 256자를 넘는 ID를 거부한다.
- 시나리오: 서버가 base64url 랜덤 ID를 발급하면 약 3%가 `-`/`_`로 시작한다. 세션 생성과 checkpoint 저장은 통과하지만, 이후 part마다 `issueUploadPart`가 `INVALID_INPUT`(재시도 안 함)으로 실패한다. 같은 ACTIVE 세션을 재사용하므로 만료나 abort 전까지 계속 실패한다. complete에서 받은 resourceId를 `issueDownload`에 넘길 때도 같다.
- 수정 방향: ID 문법을 한 곳에 두고 provider와 executor가 import한다.
- 테스트: fixture는 안전한 ID만 쓴다.
3. **[필수·확인됨] 기본 정책에서 동시 업로드가 조용히 1로 줄어듦 (문서와 반대)**
- 위치: `resumable-upload/runtime-policy.ts:101-117`, `:140-141`, `resumable-upload-runtime.ts:806-819`
- 문제: 기본값에서 `maxInFlightBytes 20MiB / (partSize 5MiB × copyFactor 4) = 1`이라 `workerCount = min(3, …, 1) = 1`이다. `maxConcurrency: 3`은 효과가 없는데 createSession은 서버에 concurrency 3을 요청한다. `docs/architecture/presigned-transfer-and-image-cdn.md:257`은 `partSize × concurrency × copyFactor`가 한도를 넘으면 시작 전에 거절하라고 한다. 코드는 `partSize × copyFactor`만 검사하고 조용히 clamp한다. copyFactor 4는 part마다 방어적 복사가 4~5번 일어나서 필요하다(`presigned-upload-part-executor.ts:274`의 `Uint8Array.from`, executor `slice()` 등).
- 수정 방향: 정책 검증에 `maxConcurrency`를 곱해 문서대로 거절하거나 기본값을 맞춘다. 겹치는 복사는 하나로 줄인다.
- 테스트: 테스트는 항상 정책을 override해서 기본 정책의 실제 동시성은 검증하지 않는다.
4. **[필수·확인됨 ✓] 크기 초과 파일이 `LIMIT_EXCEEDED`가 아니라 `INVALID_INPUT`으로 보고됨**
- 위치: `resumable-upload-runtime.ts:1755-1761`, `:217-221`, `:385-392`
- 문제: `snapshotRequest`가 한도 초과에 TypeError를 던지고 `upload()`의 catch가 `INVALID_INPUT`으로 바꾼다. `executeUpload`의 `LIMIT_EXCEEDED` 분기는 같은 policy로 다시 검사하므로 실행될 수 없다.
- 시나리오: 6GB 파일을 올리면 UI가 "파일이 너무 큽니다" 대신 "잘못된 입력"을 받는다.
- 수정 방향: `snapshotRequest`에서 크기 검사를 빼고 `executeUpload` 분기를 살린다.
- 테스트: 없음.
5. **[권장·확인됨] 한 worker가 실패해도 다른 worker가 취소되지 않음**
- 위치: `resumable-upload-runtime.ts:820-865`
- 문제: `firstFailure`는 다음 루프에서만 확인한다. in-flight worker는 retry 횟수만큼 issue와 PUT을 반복한다(시도당 30초 timeout + backoff). 호출자는 최악의 경우 몇 분 뒤에 실패를 받는다.
- 수정 방향: transfer 단위 AbortController를 `request.signal`과 합치고 `firstFailure` 설정 시 abort한다.
- 테스트: 없음.
6. **[권장·가능성] 손상되었거나 모르는 schema의 checkpoint 행이 upload와 abort를 모두 막음**
- 위치: `resumable-upload/indexeddb-checkpoint-store.ts:314-318`, `resumable-upload-runtime.ts:1149-1150`
- 시나리오: 같은 DB 버전에서 새 빌드가 schemaVersion 2 행을 씀 → 롤백 → 해당 uploadKey는 read와 abort가 모두 `CORRUPT_DATA`로 영구 실패. 복구하려면 partition 전체를 삭제해야 한다.
- 확인 방법: 새 schema 행을 넣고 abort를 호출한다.
- 수정 방향: abort 경로에 "해석할 수 없는 행은 revision을 무시하고 삭제" 분기를 두고 ORPHANED로 보고한다.
7. **[권장·가능성] image preset `fit: "inside"/"outside"` + PRIMARY_REQUIRED probe 조합에서 비율이 다른 asset이 모두 실패**
- 위치: `image-cdn/image-cdn-policy.ts:116-122`, `:468`, `image-cdn-runtime.ts:496-503`, `:1019-1020`, `browser-image-probe.ts:211-219`
- 문제: probe는 decode 크기가 `primary.pixelWidth × pixelHeight`와 정확히 같아야 통과한다. inside/outside는 원본 비율을 유지하므로 크기가 다르게 나와 `INTEGRITY_FAILED`가 된다. PRIVATE_SIGNED는 PRIMARY_REQUIRED가 강제라 이 조합을 쓸 수 없다.
- 확인 방법: 대상 CDN의 fit 의미를 확인한다. 테스트는 `fit: "cover"`만 쓴다.
- 수정 방향: PRIMARY_REQUIRED일 때 fit을 cover/contain/fill로 제한하거나, 예상 출력 크기를 계산해 비교한다.
8. **[권장·가능성] 이미지 probe가 EXIF/`irot` 회전을 고려하지 않음**
- 위치: `image-cdn/browser-image-probe.ts:51-53`, `:231-235`
- 문제: 헤더 파서는 회전 전 크기를 읽고, `createImageBitmap`은 기본으로 EXIF orientation을 적용한다. orientation 5~8 JPEG나 `irot` AVIF는 폭과 높이가 뒤바뀌어 거절된다(fail-closed라 보안 문제는 아님).
- 확인 방법: CDN이 출력에서 EXIF를 제거하는지 확인한다.
- 수정 방향: `createImageBitmap(blob, { imageOrientation: "none" })`.
9. **[권장·확인됨] presigned HTTP helper 중복과 동작 차이, 죽은 helper**
- 위치: `presigned/presigned-transfer-executor.ts:997-1178`, `presigned/presigned-capability-http-provider.ts:834-1032`, `resumable-upload-runtime.ts:1299-1349`
- 문제:
- `createAbortScope`, `readWithSignal`, `transferFailure`, `isAbortSignal`, `byteBucket`, `cancelBody`가 두 파일에 거의 그대로 있다.
- `statusFailure`의 401/403 recovery가 executor는 `REISSUE_CAPABILITY`, provider는 `NONE`이다.
- executor의 `compensateLateResponse`(`:1052`)는 호출하는 곳이 없다.
- download의 `Number(declaredLength)`(`:787`)는 `"1e3"`, `"0x10"`, `""`를 통과시킨다.
- runtime의 `invokeProviderAttempt`만 kernel `createAbortableOperation`을 쓰지 않는다.
- 수정 방향: `presigned/http-common.ts`로 모으고 runtime attempt를 kernel 위로 옮긴다.
10. **[권장·확인됨] `resumable-upload-runtime.ts` 2298줄**
- 위치: `resumable-upload-runtime.ts:1422-1705`, `:1772-2020`
- 문제: upload 흐름, retry/deadline, 서버 응답 검증, 의존성 snapshot 래퍼 8개가 한 파일에 있다. 검증과 snapshot만 분리해도 약 800줄이 줄어든다.
11. **[사소·확인됨] vault `register`가 snapshot 뒤에 원본 객체를 다시 읽음**
- 위치: `presigned/presigned-capability-vault.ts:279-287`
- 문제: 중복 receipt 검사는 `registration.capabilityReceipt`(원본)를 읽고 저장은 `snapshot.capabilityReceipt`로 한다. stateful issuer면 중복 검사를 우회할 수 있다. issuer가 내부 코드라 영향은 작다.
- 수정 방향: 세 곳 모두 `snapshot.capabilityReceipt`를 쓴다.
잘 된 점: presigned vault의 SSRF·capability 유출 방어(WeakMap 식별자, 1회용 replay guard, `redirect: "error"`, `credentials: "omit"`, 경로 이중 인코딩 차단). 이미지 헤더 파서의 bounds check와 P-256 서명 검증. adapter 간 import 규칙 준수.
### 6.2 browser-files / cache-storage / cross-context-invalidation
요약: 다운로드 abort 경로에서 Result 계약이 깨지고, cross-tab 무효화가 60초마다 전체 무효화로 떨어진다. 기본 cache 정책은 실제 CDN 응답을 거부하고, 조회 비용이 크다.
1. **[필수·확인됨] BOUNDED_OBJECT_URL + presigned source에서 open 실패 시 `deliver()`가 reject되고 lease가 샘**
- 위치: `src/adapters/browser-files/download-delivery-adapter.ts:733-743`
- 문제: `promptAndStream`은 `resolveByteSource`를 try/finally 안에서 부르지만 `boundedObjectUrlHandoff`는 try 밖에서 부른다. `resolveByteSource`는 `open()` 동기 throw(1085), open 중 abort(1095), `pendingOpen` reject 때 throw한다.
- 시나리오: 사용자가 취소 → `deliver()`가 `{ok:false, ABORTED}` 대신 AbortError로 reject된다. observer 기록도 없다. `closeHeldSource`가 호출되지 않아 늦게 온 lease는 `compensateLateSource`(1039)가 닫지 않는다.
- 수정 방향: `resolveByteSource`부터 try/finally로 감싸고 catch에서 `mapDownloadException`으로 Result를 반환한다.
- 테스트: 기존 테스트는 PROMPT_AND_STREAM만 쓴다.
2. **[필수·확인됨 ✓] sequence 기준점이 이벤트 TTL(60초)과 함께 삭제되어 60초 이상 쉰 뒤 이벤트가 매번 GAP**
- 위치: `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts:494-503`, `:544-554`
- 문제: watermark가 `expiresAt: event.expiresAt`로 저장되고 `pruneTracking`이 지운다. 다음 이벤트는 `!previous && event.sequence > 1`로 GAP이 된다. 받는 쪽 `src/adapters/query-cache/tanstack-cache-coordinator.ts:106-110`은 GAP이면 모든 topic을 무효화한다.
- 시나리오: 탭 A에서 몇 분에 한 번 수정할 때마다 탭 B가 모든 namespace의 active 쿼리를 다시 가져온다.
- 수정 방향: watermark 수명을 이벤트 TTL과 분리한다. 메모리는 이미 `sourceCapacity` LRU로 제한된다.
- 테스트: TTL 테스트(`tests/unit/cross-tab-invalidation.test.ts:618`)는 서로 다른 source에 seq 1만 보낸다.
3. **[필수·확인됨] storage fallback 탭이 다른 탭의 이벤트를 못 받는데 상태는 정상으로 표시됨**
- 위치: `browser-cross-context-invalidation.ts:349-373`
- 문제: broadcast 발행에 성공하면 storage pulse를 쓰지 않는다. `postMessage`가 한 번 실패한 탭은 `closeBroadcast()`(369)로 수신 listener까지 제거한다. 그 뒤로 다른 탭의 broadcast를 못 받는데 status는 `ACTIVE_STORAGE_FALLBACK`이다.
- 수정 방향: 발행 실패 시 송신만 storage로 바꾸고 수신은 유지한다. 또는 발행 쪽이 broadcast와 storage 모두에 쓴다(eventId dedupe 있음). 아니면 DEGRADED로 보고한다.
- 테스트: `tests/unit/cross-tab-invalidation.test.ts:463`은 발행 탭에 `failPost = true`를 걸어 문제 경로를 우회한다.
4. **[필수·확인됨(Web IDL 기준)] 브라우저 picker 함수를 options 객체에 bind함**
- 위치: `src/adapters/browser-files/browser-file-picker.ts:434-435`, `download-delivery-adapter.ts:225-229`
- 문제: `showOpenFilePicker.bind(options)`는 `this`를 options로 고정한다. Window operation은 `this`가 Window가 아니면 TypeError("Illegal invocation")를 던진다. `window.showOpenFilePicker`를 그대로 넘기면 매번 실패한다.
- 확인 방법: `window.showOpenFilePicker.call({}, {})`가 TypeError인지 본다. user gesture 없이 확인할 수 있다.
- 수정 방향: bind 없이 호출하거나 composition 단계에서 `window`에 bind한 host를 주입한다.
5. **[필수·코드 경로 확인됨, 전제는 실제 서버 동작] 기본 cache 정책이 `Vary: Accept-Encoding` 응답을 전부 거부**
- 위치: `src/adapters/cache-storage/public-response-cache-adapter.ts:1299-1333`, `public-cache-policy.ts:69`
- 문제: `allowedVaryHeaderNames: []`라 Vary가 있으면 `POLICY_REJECTED`다. nginx `gzip_vary`와 대부분의 CDN이 JS/CSS에 이 헤더를 붙인다. `accept-encoding`은 브라우저가 Request에서 지우는 금지 헤더라 정책으로 풀기도 어렵다. `allowedResponseHeaderNames`에서 `content-type`을 빼면 activate가 항상 `INTEGRITY_FAILED`가 되는데 `assertPublicCachePolicy`가 이를 막지 않는다.
- 수정 방향: `accept-encoding`을 브라우저 관리 Vary로 따로 허용하고, `content-type` 필수 검사를 정책 검증에 추가한다.
- 테스트: `tests/browser-capabilities/public-cache-storage.spec.ts:106-125`는 Vary 없는 응답만 쓴다.
6. **[권장·확인됨] 캐시 조회 한 번의 비용이 큼**
- 위치: `public-response-cache-adapter.ts:1453`, `:263-319`, `:1540-1544`
- 문제: `matchActiveExact` 한 번에 `keys()` 2번, 2 MiB 버퍼 2개(총 4 MiB) 선할당, 최대 10k asset marker 전체 재검증과 SHA-256, 선형 탐색, 본문 SHA-256과 복사 3~4회가 일어난다. SW처럼 요청마다 조회하면 페이지 로드 한 번에 수백 MiB 할당이 생긴다.
- 수정 방향: JSON은 chunk를 모아 읽고, 검증된 marker를 `cacheName+manifestDigest`로 메모리 캐시하고, asset 탐색은 Map으로 바꾼다.
7. **[권장·가능성] kernel의 abort race를 손으로 다시 구현해 틈이 생김**
- 위치: `download-delivery-adapter.ts:1032-1050`, `:1482-1524`, `browser-file-vault.ts:872-891`
- 문제: `combineAbortSignals`(동일 복사본 2개), `awaitWithSignal`, `compensateLateSource`가 `src/adapters/platform/abortable-operation.ts:90`을 다시 구현한다. abort 직후 finally 전 몇 microtask 사이에 lease가 resolve되면 아무도 닫지 않는다. `awaitWithSignal(handle.createWritable(), signal)`(595)은 늦게 온 writable을 abort하지 않는다(Chrome `.crswap` 임시 파일).
- 수정 방향: kernel `race`와 compensate로 교체한다.
8. **[권장·가능성] native `cancel` 지원 브라우저에서도 focus fallback이 켜져 있어 느린 `change`가 버려짐**
- 위치: `src/adapters/browser-files/browser-file-picker.ts:301-317`
- 시나리오: Android 클라우드 provider처럼 파일을 받아온 뒤 change를 보내는 경우, 사용자가 파일을 골랐는데 "취소됨"으로 처리된다.
- 수정 방향: native `cancel`을 한 번이라도 관찰하면 fallback을 끈다.
- 테스트: `tests/unit/browser-file-picker.test.ts:215`는 grace 안에 도착하는 경우만 본다.
9. **[권장·확인됨] host factory가 조용히 `undefined`를 반환해 cross-tab 기능이 진단 없이 꺼짐**
- 위치: `src/adapters/cross-context-invalidation/browser-cross-context-host.ts:52-62`
- 시나리오: `RELEASE_ID`가 `1.2.3+sha.abc`, `feature/x`, `app@1.2.3`처럼 `+`, `/`, `@`를 포함하거나 120자를 넘으면 `cacheEpoch` 검사에 실패해 `undefined`가 반환된다. `RELEASE_ID` 자체는 빈 문자열만 아니면 통과한다(`src/contracts/deployment-admission.ts:95-106`).
- 수정 방향: 반환 전 `observe(OPEN, FAILED)`를 호출하고, epoch는 releaseId를 hash/인코딩해 만든다.
10. **[권장·확인됨] 파일명 자르기가 O(n²)이고 입력 길이 상한이 없음**
- 위치: `src/adapters/browser-files/file-policy.ts:357-362`
- 시나리오: 서버가 10만 자 파일명을 주면 약 10^10번 연산으로 탭이 멈춘다. deliver 한 번에 두 번 호출된다(`download-delivery-adapter.ts:318`, `:1003`).
- 수정 방향: 루프 전에 `maxUtf8Bytes`개 code point로 먼저 자른다.
11. **[권장·확인됨] 1000줄 넘는 파일 2개**
- `public-response-cache-adapter.ts`(1949줄): facade, 조회/stage/activate/cleanup, 매니페스트·marker 코덱(약 400줄), 응답 검증(약 200줄).
- `download-delivery-adapter.ts`(1528줄): 전략 3개, 입력 검증, abort 유틸.
12. **[사소·확인됨] 중복 helper와 죽은 분기**
- `MEDIA_TYPE` 정규식 3곳: `object-url-lease.ts:187`, `download-delivery-adapter.ts:137`, `browser-file-policy-registry.ts:84`.
- `safeOpaqueValue`(`browser-file-vault.ts:868`)와 `safeGeneratedToken`(`download-delivery-adapter.ts:1376`)이 같은 정규식이다.
- `object-url-lease.ts:112-118`의 안쪽 `if`는 바깥 조건과 반대라 실행되지 않는다.
잘 된 점: cross-context wire 이벤트의 파싱 검증(key 집합, 크기, epoch, topic 허용 목록, TTL). cache stage 경로의 abort 뒤 쓰기 차단과 교체본 검증 전 기존 candidate 보존. object URL의 단일 lease registry.
### 6.3 http / browser-rpc / query-cache / auth / diagnostics / telemetry
요약: V3 실행기의 자원 한도, 마감, abort 관리는 좋다. 문제는 URL 조립, 오류 분류, 자격증명 헤더 검증, 세션 변경 시 scope fence에 있다.
1. **[필수·확인됨 ✓] 경로 값 `.`/`..`가 URL 정규화로 다른 엔드포인트를 가리킴**
- 위치: `src/adapters/http/http-contract-bridge.ts:185-205`, `src/adapters/http/request-builder.ts:72-86`, `:106`
- 문제: `/`와 `\`만 막는다. `encodeURIComponent("..")`는 `..` 그대로이고 `new URL`이 상위 경로로 해석한다. 결과가 base 경로 아래라 `URL_ORIGIN_ESCAPED`도 통과한다.
- 시나리오: `/v1/projects/{p}/members/{m}`에 `m=".."` → `/v1/projects/p1/`. DELETE 명령이면 멤버가 아니라 프로젝트 쪽으로 요청이 간다. 레퍼런스 스키마 `resourceId: z.string().trim().min(1).max(120)`(`reference-schemas.ts:24`)는 `".."`를 통과시킨다. V2도 `base.pathname =` 대입에서 같은 정규화가 일어난다.
- 수정 방향: 값이 `"."`이나 `".."`이면 `PATH_VALUE_INVALID`로 거절한다. `src/contracts/release-artifacts.ts:37`에 같은 규칙이 있다.
- 테스트: `PATH_VALUE_INVALID`, `URL_ORIGIN_ESCAPED` 모두 없음.
2. **[필수·흐름은 확인됨, 무한 반복은 가능성] 세션 알림마다 무조건 scope fence + V3가 "요청 전 자격증명 없음"과 "서버 401"을 구분하지 못함**
- 위치: `src/adapters/query-cache/server-state-scope-runtime.ts:90-105`, `src/adapters/http/http-execution-v3.ts:709-712` / `1155-1163`, `src/adapters/auth/external-session-adapter.ts:111-114`, `:135`
- 문제: scope 런타임은 `session.subscribe` 알림마다 상태 비교 없이 generation을 올리고, 진행 중 요청을 abort하고, 캐시를 비운다. V3는 요청 전 `UNAUTHENTICATED`와 서버 401을 같은 결과로 돌려주고, 조합 루트(`src/bootstrap/runtime-adapters.ts:462`, `:520`)가 둘 다 `onUnauthenticated()`를 부른다. demo `setState`는 값이 같아도 알림을 보낸다.
- 시나리오: 로그아웃 상태에서 V3 쿼리 실행 → `onUnauthenticated` → 알림 → fence → 캐시 비움 → 쿼리 재마운트 → 반복 가능. `recovery-pending` 상태의 요청은 demo가 `"unauthenticated"`로 덮어 복구가 끊긴다. 외부 owner가 토큰 갱신 때도 알림을 보내면 갱신마다 캐시가 비워진다. presentation 쪽 영향은 6.8-3.
- 확인 방법: demo 모드, 로그아웃 상태에서 쿼리가 켜진 페이지를 열고 FENCED 이벤트 횟수를 센다.
- 수정 방향: (state, 식별자)가 바뀔 때만 fence한다. demo `setState`는 같은 값이면 알리지 않는다. V3의 요청 전 판정을 서버 401과 구분한다.
- 테스트: "상태가 그대로인 알림" 테스트 없음.
3. **[필수·확인됨] 게이트웨이 5xx(HTML/빈 바디)가 계약 위반으로 분류되어 status가 사라지고 "지원팀 문의, 재시도 불가"로 표시**
- 위치: `src/adapters/http/http-execution-v3.ts:1486-1510`, `:300-306`, `src/adapters/http/feature-http-binding.ts:356-362`, `:366-390`, `src/adapters/http/client.ts:858-869`
- 문제: nginx `text/html` 502는 재시도 후 `CONTRACT_VIOLATION{CONTENT_TYPE_MISMATCH}`, 빈 바디는 `PROBLEM_SCHEMA_INVALID`가 된다. metadata가 없어 `httpStatus`와 `http_status_group`이 빠진다. 바인딩을 거치면 `retryable:false`, `action:"contact-support"`다. V2는 content-type 검사가 status 검사보다 먼저이고 `retry-policy.ts:1`에 이 종류가 없어 재시도도 안 한다. 입력 검증 실패(`FINAL_REQUEST_INVARIANT_FAILED`)와 `MISSING_IDEMPOTENCY_KEY`도 기본값 `ENVELOPE_MISMATCH`로 떨어진다(`feature-http-binding.ts:388`).
- 수정 방향: 5xx/408/425에서 problem 바디가 유효하지 않으면 status를 담은 서버 장애로 끝낸다. 요청 쪽 위반은 `VALIDATION_REJECTED` 계열로 매핑한다.
- 테스트: 없음.
4. **[필수·확인됨] 자격증명 헤더 값 검증이 CR/LF만 막아, NUL/비 Latin-1 토큰이 "전송 후 네트워크 실패"로 분류됨**
- 위치: `src/adapters/http/http-contract-bridge.ts:83-90`, `http-execution-v3.ts:893-907`, `:927`, `src/adapters/auth/external-session-adapter.ts:37-46`
- 문제: `new Headers({authorization:"Bearer 한"})`는 TypeError, `fetch`는 reject된 Promise를 준다. V3는 `fetcher()`가 Promise를 반환한 시점에 `DISPATCHED`로 표시하므로 명령은 `MAYBE_APPLIED` + NETWORK_FAILURE, 쿼리는 재시도 예산만 쓴다. 검증기가 3벌이고, auth 어댑터는 대소문자만 다른 중복 헤더를 조용히 합친다. `decodeCredentialPatch`(`http-execution-v3.ts:1100-1106`)는 UTF-16 길이, bridge는 UTF-8 바이트로 잰다.
- 수정 방향: bridge 한 곳에서 제어문자 없는 ByteString을 검사하고, `checkFinalInvariants`에서 `new Headers(headers)`를 미리 만들어 본다.
- 테스트: `CREDENTIAL_HEADER_VALUE_INVALID` 테스트 없음.
5. **[필수·확인됨] feature 바인딩이 `mapSuccess`/`mapProblem` 예외를 잡지 않음**
- 위치: `src/adapters/http/feature-http-binding.ts:300`, `:311`
- 문제: V2(`client.ts:919-956`), `mapWithBoundaryRegistry`, RPC `mapResponse`는 try/catch로 감싸는데 여기만 없다. 매퍼가 던지면 `execute`가 reject되고, 서버가 `APPLIED_CONFIRMED`로 확정한 명령도 `normalizeUnknownFailure`를 거쳐 `MAYBE_APPLIED`가 된다(`src/presentation/adapters/query/application-query.ts:726-727`).
- 수정 방향: 두 호출을 감싸 `MAPPING_CONTRACT_VIOLATION`에 `effect: outcome.effect`를 실어 반환한다.
- 테스트: 없음.
6. **[권장·확인됨] 백오프 중 scope fence가 TIMEOUT으로 분류됨 + 종료 사유 판정이 6곳에 복사됨**
- 위치: `http-execution-v3.ts:941-950`, `:1031-1040`
- 문제: 재시도 sleep 중 로그아웃하면 `terminalCancellation === "SCOPE_FENCE"`인데 코드는 `"CALLER"`만 확인해 `TRANSPORT_FAILURE{TIMEOUT}`이 된다. 사용자에게 "시간 초과, 재시도"가 뜬다. 같은 판정이 679-692, 813-822, 915-927, 941-950, 986-998, 1031-1040에 따로 있고 scope 종료가 위치에 따라 세 가지 결과로 나온다. `execute()`는 약 620줄이다.
- 수정 방향: `terminalOutcomeFor(owner, phase)` 헬퍼로 모은다.
- 테스트: caller abort 중 sleep은 있음(`tests/unit/http-execution-v3.test.ts:687`), scope fence 중 sleep은 없음.
7. **[권장·코드 경로 확인됨, 영향은 분류기에 따라 가능성] 명령의 최종 effect가 누적 certainty와 합쳐지지 않음**
- 위치: `http-execution-v3.ts:1045`, `:1486-1497`, `:1579`
- 시나리오: IDEMPOTENT DELETE가 504(빈 바디, 실제로는 적용됨) → 재시도 → 404 → 분류기가 `NOT_APPLIED`로 판정하면 최종 결과가 "적용 안 됨, 재시도 가능"이 된다.
- 수정 방향: 명령이면 `finish` 직전 `joinMutationEffectCertainty(logical, attempt)`를 적용하거나, `MAYBE_APPLIED`면 retryHint를 false로 둔다.
- 테스트: 없음.
8. **[권장·확인됨] 무효화가 namespace별 refetch를 하나씩 기다림**
- 위치: `src/adapters/query-cache/tanstack-cache-coordinator.ts:79-89`
- 문제: TanStack 5의 `invalidateQueries`는 active refetch가 끝나야 resolve되는데 for 루프에서 순차 await한다. `lease.release()`도 이를 기다린다.
- 수정 방향: `Promise.allSettled`로 병렬 실행.
9. **[권장·가능성] Browser RPC 명령 경로에 effect certainty와 scope 확인이 없음**
- 위치: `src/adapters/browser-rpc/browser-rpc-runtime.ts:352-401`, `:424-435`, `:487-499`, `:1535-1574`
- 문제: `NON_REPLAYABLE`/`KEYED_COMMAND` unary가 전송 후 timeout/THREW/`UNAVAILABLE`이면 `retryable:true`, `action:"retry"`로 나간다. 재시도 전 generation을 확인하지 않아 로그아웃 뒤에도 이전 사용자 요청이 재전송될 수 있다. server stream은 소비자가 `return()`을 안 부르면 `RPC_STREAM_DRAINING`에 막힌다.
- 수정 방향: 전송 후 실패에 `effect: "MAYBE_APPLIED"`를 붙이고, 매 attempt 전 `safeIsCurrent`를 확인하고, abort 리스너에서 항목을 정리한다.
10. **[권장·확인됨] best-effort 텔레메트리 fetch에 타임아웃이 없고 전송기가 두 벌**
- 위치: `src/adapters/telemetry/best-effort-telemetry.ts:211-238`, `src/adapters/telemetry/feature-telemetry.ts:23-36`
- 문제: 수집기가 응답하지 않으면 `activeFlush`가 끝나지 않아 이후 flush가 모두 이 Promise를 받고, 큐가 차면 세션 동안 텔레메트리가 꺼진다. feature 쪽은 `credentials:"omit"`, best-effort 쪽은 기본값(same-origin)이라 쿠키가 같이 간다.
- 수정 방향: `AbortSignal.timeout(...)`을 걸고 `createFetchTelemetryTransport` 하나로 통일한다.
11. **[권장·확인됨] V2 관련 두 가지**
- 401 복구가 재시도 예산에 묶여 있다(`src/adapters/http/client.ts:339-344`). `MAX_RETRY_ATTEMPTS=0`이거나 503 → 401 순서면 복구 없이 로그아웃된다. `auth-recovery.test.ts`에 없음.
- "롤백 가능 seam" 문제가 알려진 것보다 넓다(`src/adapters/http/schema-registry.ts:12-16`). 슬롯 4개를 모두 주입해도 V2는 `{success,data,meta}` 봉투를, V3는 DTO 자체를 검증한다(`http-execution-v3.ts:1325`). 같은 백엔드로 V2로 되돌리면 모든 응답이 `ENVELOPE_MISMATCH`다.
12. **[권장/사소·확인됨] 기타**
- `src/adapters/query-cache/cursor-pagination-runtime.ts:111-114`: 페이지마다 누적 items 전체를 `JSON.stringify`(O(pages × 누적 크기)). `items.push(...page.items)`는 큰 페이지에서 RangeError로 reject된다.
- `browser-rpc-runtime.ts:1468`의 `validTransportFailure`는 쓰는 곳이 없고 RPC-RR-04 주석이 금지한 직접 속성 읽기를 한다. `decodeTransportFailure`와 중복이다.
- `src/adapters/query-cache/conditional-validator-store.ts:141-146`: 닫는 따옴표 없는 `W/"`를 유효 ETag로 받는다.
잘 된 점: V3의 모든 대기(자격증명, lease, fetch, 바디, 백오프)를 하나의 수명 signal과 경쟁시키고 늦은 응답의 바디를 취소한다. 바디는 선언 길이 → 스트림 누적 → JSON 구조 예산 순으로 제한한다. conditional validator 키를 튜플 `JSON.stringify`로 만들어 구분자 충돌을 막았다.
### 6.4 realtime (`src/adapters/realtime/`)
요약: 경계 검증과 상한은 꼼꼼하다. 문제는 모듈 연결 지점에 있다. 멈춘 effect와 recovery가 겹치고, WS/SSE가 끊김 뒤 재연결하지 않고, barrier NONE 스트림이 recovery 한 번에 종료된다. SSE 파서는 느리다.
1. **[필수·확인됨] recovery가 DRAINING effect와 동시에 실행되고 `recoveryRequired`를 해제함**
- 위치: `src/adapters/realtime/stream-coordinator.ts:707-721`
- 문제: DRAINING 검사는 진입 시점(`:666`)에만 있다. `await quiescence` 뒤에는 closed/abort/scope만 본다. 그 사이 effect가 timeout으로 DRAINING이 되어도 recovery가 authority를 호출하고 `:843`에서 커밋한다. 늦게 끝난 effect가 snapshot을 덮어쓸 수 있다(RT-RR-01/02가 막으려던 상황).
- 재현: `recover(SEQUENCE_GAP) called; effectStillRunning=true` → `hasResumeState:true` → `late effect settled`.
- 수정 방향: `await quiescence` 직후 `state.lifecycle === "DRAINING"`이면 실패를 반환한다.
- 테스트: 없음(`:503`은 협조적 apply, `:1282`는 scheduler 고장만).
2. **[필수·확인됨 ✓] 네트워크 끊김, 서버 재시작, 502/504 뒤 재연결하지 않음**
- 위치: `src/adapters/realtime/reconnect-coordinator.ts:1661-1671`
- 문제: `reconnectable()`은 `PROVIDER_UNAVAILABLE`/`RATE_LIMITED`에 `serverNotBeforeMs`가 없으면 `retryable:true`여도 false를 반환한다. 전송 계층은 hint 없이 이 값을 보낸다: WS `RESTART`/`NETWORK_LOST`(1006/1001/1012, `websocket/websocket-connection.ts:1923-1930`), error 이벤트(`:429-443`), SSE 502/504(`sse/fetch-sse-connection.ts:588-590`). WS에는 Retry-After가 없어 hint가 생길 수 없다. 결과적으로 WS는 IDLE_TIMEOUT, CONNECT_TIMEOUT, OFFLINE일 때만 재연결한다. 설계 문서(`docs/architecture/realtime-events-web-push-and-bounded-polling.md:1008`, `:1150-1156`)는 이들을 bounded reconnect로 정의한다. polling도 같은 규칙이다(`polling/bounded-poll-coordinator.ts:344-351`).
- 수정 방향: "hint 필수" 조건을 빼고 `retryable`만 본다. 전송 계층은 hint가 필요한데 없으면 이미 `retryable:false`를 보낸다(SSE `:573-587`, WS OVERLOADED `:1931-1937`).
- 테스트: 양쪽 동작이 각각 고정되어 있다(`realtime-reconnect-coordinator.test.ts:308-331`, `websocket-connection.test.ts:930-957`). 둘을 잇는 통합 테스트는 없다.
3. **[필수·확인됨] barrier NONE 스트림이 recovery 한 번으로 PROTOCOL_MISMATCH 종료**
- 위치: `src/adapters/realtime/event-consumer.ts:181-194`
- 문제: consumer는 모든 `RECOVERED`를 `RECOVERY_COMMITTED`로 넘긴다. SNAPSHOT_ONLY + barrier NONE 스트림은 barrier를 기다리지 않는다(`stream-coordinator.ts:844-848`). 전송이 연결을 닫고 → reconnect가 `confirmTransportBarrier` 호출(`reconnect-coordinator.ts:769-803`) → `stream-coordinator.ts:986-994`가 PROTOCOL_MISMATCH를 반환하고 종료된다.
- 재현: gap 이벤트 → `RECOVERY_COMMITTED` → `confirmTransportBarrier: PROTOCOL_MISMATCH`.
- 수정 방향: barrier가 필요 없는 recovery는 `CONTINUE`로 넘긴다. disposition에 barrier 필요 여부를 싣는다.
- 테스트: `event-consumer.test.ts`는 accept를 mock해서 이 조합을 못 본다.
4. **[필수·확인됨] SSE 파서가 문자마다 `TextEncoder.encode`를 호출해 250KB chunk에 120~170ms**
- 위치: `src/adapters/realtime/sse/sse-parser.ts:166-167`
- 측정: 250KB chunk 121~169ms(약 2MB/s). 같은 데이터를 `split`으로 처리하면 1.3ms.
- 문제: 메인 스레드 코드라 재연결 직후 replay 같은 몰아치는 수신이 long task가 된다.
- 수정 방향: `indexOf`로 줄바꿈을 찾아 `slice`하고 UTF-8 길이는 코드포인트 범위로 계산하거나 줄마다 한 번만 센다.
- 테스트: 성능 테스트 없음.
5. **[권장·가능성] `maxItemsPerChunk`(256)를 넘으면 non-retryable QUEUE_OVERFLOW로 종료**
- 위치: `sse/sse-parser.ts:282-294`, `fetch-sse-connection.ts:437-441`
- 재현: 333바이트 이벤트 300개(104KB) chunk 하나 → `QUEUE_OVERFLOW retryable:false`.
- 문제: 메모리는 `maxChunkBytes`가 이미 막는다. 이 상한은 정상적인 몰아치기 수신만 죽인다.
- 확인 방법: replay 중 실제 reader chunk 크기를 측정한다.
- 수정 방향: 남은 텍스트를 다음 처리로 넘기거나 상한을 없앤다. COMMENT는 상수 객체를 재사용한다.
6. **[권장·확인됨] dedupe가 가득 차면 매번 전체 recovery, fingerprint로 원문 전체 저장**
- 위치: `stream-coordinator.ts:490-502`, `event-codec.ts:189`, `stream-coordinator.ts:1108-1126`
- 문제: 초당 3.4건 이상(2048건/600초)이 계속 오면 윈도우마다 snapshot 재수신과 재연결이 일어난다. fingerprint가 canonical envelope 전체(최대 64KB)라 4MB 한도가 빨리 찬다. `pruneDedupe`는 시간순 항목에서 `break` 대신 `continue`를 써서 매번 전부 훑는다. 주석끼리도 어긋난다(`:621` "eviction 금지", `:1681` "2,048 ID 또는 10분").
- 수정 방향: FIFO 제거, fingerprint는 해시로, prune에서 `break`.
7. **[권장·확인됨] heartbeat 한 번이면 재시도 예산이 초기화되어 불안정한 서버에 끝없이 재연결**
- 위치: `reconnect-coordinator.ts:950-961`, `:980-990`, `reconnect-policy.ts:135`
- 시나리오: 연결 후 `:` comment 하나 보내고 끊는 서버/프록시 → `attemptIndex`가 0에 머물고 대기가 [0, baseDelay)라 `maxAttempts`/`maxElapsed`에 도달하지 못한다. 여러 클라이언트가 동시에 몰린다.
- 수정 방향: 유효 신호가 있고 동시에 `stableOpenMs`가 지났을 때만 초기화한다.
8. **[권장·확인됨] 같은 로직의 복사본과 동작 차이**
- DataSnapshot 3벌: `result.ts:141`(`Object.hasOwn` + frozen 계산), `reconnect-coordinator.ts:1485`(`"value" in`), `polling/bounded-poll-coordinator.ts:789`(enumerable 검사 없음, null prototype 거부).
- abort/timeout race 6종: `fetch-sse-connection.ts:601`, `reconnect-coordinator.ts:1036`, `:1058`(전역 `setTimeout` 사용), `bounded-poll-coordinator.ts:563`, `:605`, `live-poll-handoff-coordinator.ts:673`, `:696`(본문 동일), `stream-coordinator.ts:204`, WS 인라인 2곳.
- 영역 밖: `json-member-scanner.ts`와 `web-push/push-codec.ts:211`(최상위 키만 검사). `reconnect-policy.ts:147`과 `http/retry-policy.ts:17`(http 쪽은 `" "`를 0ms로, `"1e3"`, `"1.5"`도 허용).
- 수정 방향: realtime 내부는 `result.ts`로, 여러 adapter 공용은 kernel로 올린다.
9. **[권장·확인됨] 거대 함수와 무시되는 파라미터**
- `reconnect-coordinator.ts:307-1016`: `run()` 약 700줄. 정리 코드 4줄이 약 15번 반복된다.
- `websocket/websocket-connection.ts:1987-2003`: `failure()`/`connectionFailure()`의 4번째 인자 `_recovery`를 무시한다. 호출부 41곳이 값을 넘기지만 효과가 없다.
- 수정 방향: `endAttempt()` 헬퍼, `_recovery`는 제거하거나 receipt에 싣는다.
10. **[권장·확인됨] probe 버퍼 상한이 현재 버퍼가 아니라 누적 수신량 기준**
- 위치: `src/adapters/realtime/live-poll-handoff-coordinator.ts:266-282`
- 문제: `acceptedEvents`/`acceptedBytes`가 drain(`:522-541`)에서 줄지 않는다. 활성화 중 누적 256건을 넘으면 `failClosed()`로 영구 CLOSED.
- 테스트: 없음.
11. **[사소]**
- `bounded-poll-coordinator.ts:284-289`: `execute` throw가 무조건 OFFLINE + `retryable:false` 종료(`:344-351`). 다른 곳의 OFFLINE은 retryable이다.
- `sse-parser.ts:56-59`, `:138-141`: BOM을 두 번 제거한다(스펙은 한 번).
- `event-codec.ts:104`, `:108`: 원문을 두 번 encode한다.
- `fetch-sse-connection.ts:308`: 이벤트마다 `new TextEncoder()`.
- `websocket-protocol.ts:472-484`: `exceedsUtf8ByteLimit` JSDoc이 `utf8ByteLength` 위에 붙어 있다.
잘 된 점: 신뢰할 수 없는 프레임 처리 순서(바이트 상한 → 중복 키 스캔 → `JSON.parse` → 정확한 키 검사 → freeze). 모든 queue/buffer/rate의 상한. generation/lease로 늦은 콜백 차단. 위험 경로 대부분의 단위 테스트(15개 파일).
### 6.5 storage / adapter kernel / browser-file-storage
요약: kernel(connection/transaction/abortable)과 Web Storage 코덱은 튼튼하다. OPFS GC가 멈추고, dedup 재사용 청크를 지울 수 있고, 전역 lock과 60초 RPC 타임아웃이 겹친다. IndexedDB purge는 손상 행 하나에 막히고, 저장 스키마 검증기가 갈라져 있다.
1. **[필수·확인됨 ✓] OPFS orphan GC가 앞쪽 100개에서 더 나아가지 못함**
- 위치: `src/adapters/storage/opfs/opfs-worker-runtime.ts:995-1022`, `opfs-byte-store-adapter.ts:1099-1158`
- 문제: worker의 `listOrphanCandidates`는 참조 여부를 모르고 "staging에 없고 24시간 넘은 청크"를 디렉터리 순서로 최대 100개 준다. 커밋된 청크도 포함된다. coordinator는 참조 중이면 건너뛴다. 프로토콜에 이어 볼 커서가 없다(`opfs-worker-protocol.ts:119`).
- 시나리오: 하루 넘은 커밋 청크가 100개를 넘으면 매번 같은 100개(전부 참조 중)만 받는다. 뒤에 있는 진짜 orphan은 지워지지 않고 쿼터가 샌다. 상태는 `DEADLINE_REACHED`로 보고된다.
- 수정 방향: `LIST_ORPHAN_CANDIDATES`에 `afterDigest` 커서를 추가한다.
- 테스트: `tests/unit/opfs-worker-runtime.test.ts:428`은 청크 1개만.
2. **[필수·가능성] dedup으로 재사용한 오래된 청크를 GC가 지워 커밋된 객체 손실**
- 위치: `opfs-worker-runtime.ts:1197-1211`, `:1059-1063`, `opfs-byte-store-adapter.ts:1127-1141`
- 문제: `writeImmutableChunk`는 같은 digest가 있으면 바로 `return`해 `lastModified`가 갱신되지 않는다. 참조 확인(메인 스레드 IDB)과 삭제(worker)가 원자적이지 않다.
- 시나리오(탭 2개): 참조 0인 오래된 청크 D → 탭1 reconcile이 `isChunkReferenced(D)=false` 읽음 → 탭2가 같은 파일 재업로드, D 재사용, refcount 1, staging 삭제 → 탭1의 `DELETE_ORPHAN_CHUNK`가 D 삭제 → 그 객체를 열면 `INTEGRITY_FAILED`.
- 발생 조건: 같은 탭에서는 lock FIFO가 막는다. 여러 탭에서 스레드가 지연될 때만 열린다.
- 수정 방향: dedup hit 때 mtime을 갱신한다.
- 테스트: 없음.
3. **[필수·확인됨] origin 전체 lock을 업로드 내내 잡음 + 60초 RPC 타임아웃 → 동시 업로드 실패**
- 위치: `opfs-worker-runtime.ts:362`, `:538-541`, `opfs-policy.ts:47`, `:51`, `opfs-worker-client.ts:170-176`
- 문제: `beginPut`이 공용 Web Lock(`ca-frontend-opfs-v1:mutation`)을 FINISH/ABORT까지 잡는다. 다른 BEGIN_PUT, REMOVE_OBJECT, FINALIZE_PUT, GC가 기다리고 각 RPC는 60초 타임아웃이다.
- 시나리오: 2GiB 파일 A와 작은 파일 B를 동시에 put → A가 60초를 넘기면 B는 `UNAVAILABLE`(`opfs-worker-client.ts:612-616`). 같은 시간 remove는 logical delete만 커밋되고 DEGRADED. journal 행이 COMMITTED로 남아 같은 objectId 재업로드가 reconcile 전까지 CONFLICT.
- 수정 방향: lock을 objectId/scope 단위로 좁히거나 page 쪽 put 큐를 둔다. 최소한 한계를 주석과 문서로 명시한다.
- 테스트: worker 테스트는 배타적이지 않은 `immediateLeases`(`tests/unit/opfs-worker-runtime.test.ts:202`)를 써서 경합을 보지 않는다.
4. **[필수·확인됨] IndexedDB 파티션 purge(LOGOUT/ACCOUNT_DELETION/SESSION_END)가 손상 행 하나에 영구히 막힘**
- 위치: `src/adapters/storage/indexeddb/indexeddb-runtime.ts:2584-2619`, `:2485-2531`, `:2533-2582`
- 문제: purge가 지울 행까지 `isStoredRecord` 등으로 검증하고 budget 카운터도 확인한다. 하나라도 어긋나면 `CORRUPT_DATA`로 트랜잭션이 abort되고 다음 batch도 처음부터 다시 시작한다. `deleteDatabase` 같은 우회 경로가 없다.
- 시나리오: sidecar 없는 record 1개나 budget 카운터 1 차이로 계정 삭제가 매번 실패하고 개인 데이터가 기기에 남는다.
- 수정 방향: 파티션 purge는 값 검증 없이 key로 지우고 COMPLETE 때 budget을 0으로 리셋한다. 손상은 observe로만 보고한다.
- 테스트: 손상 행 테스트는 RETENTION_SWEEP에만 있다(`tests/unit/indexeddb-runtime.test.ts:1035`).
5. **[필수·확인됨] prepared-object 검증기 3벌 → OPFS 정책을 바꾸면 기존 객체를 못 읽음**
- 위치: `opfs-worker-runtime.ts:1687-1783`(`:1739`), `indexeddb-opfs-journal.ts:1624-1720`, `opfs-worker-client.ts:664-677`
- 문제: journal은 `chunkSizeBytes >= 1`만, worker는 현재 정책값과 정확히 같아야 통과, client는 얕은 검사만 한다. `isSupportedPhysicalSchema` 3벌(`client:646`, `worker:1677`, `journal:1614`), `stableJson` 2벌(NaN 처리 다름: `worker:1648` throw, `journal:1722` `"null"`).
- 시나리오: `chunkSizeBytes`를 4MiB → 8MiB로 바꾸면(`opfs-policy.ts:77-79` 허용 범위) 기존 객체 전부 `INTEGRITY_FAILED`, FILES_READY reconcile은 `CORRUPT_DATA`, COMMITTED reconcile은 `INVALID_INPUT`으로 계속 실패.
- 수정 방향: 검증기를 한 모듈로 합치고, 저장된 객체는 manifest의 `chunkSizeBytes`로 검증한다. 정책값은 새로 쓰는 데이터에만 적용한다.
6. **[권장·확인됨, 타임아웃은 가능성] `openObject`가 객체 전체를 두 번 읽고 두 번 해시함**
- 위치: `opfs-worker-client.ts:335-347`, `opfs-worker-runtime.ts:691-735`, `:737-763`
- 문제: VERIFY_OBJECT가 모든 청크를 읽고 해시한 뒤 READ_CHUNK가 다시 읽고 해시한다. 2GiB 객체는 첫 바이트 전에 2GiB를 처리해야 하고, 60초 RPC 안에 못 끝나면 영영 열 수 없다.
- 수정 방향: 사전 검증은 manifest 대조만 하고 root digest는 스트림 끝에서 확인한다.
7. **[권장·확인됨] IndexedDB 저장 스키마 타입·검증기가 runtime/maintenance/governance에 복제됨**
- 위치: `indexeddb-runtime.ts:59-90`, `:225-303`, `indexeddb-maintenance.ts:40-79`, `:124-229`, `indexeddb-governance.ts:282-305`
- 문제: `Stored*` 타입, `isStored*`, 측정 공식, `countBucket`, `failureOf`가 두 파일에 있고 governance에 세 번째 budget 검사가 있다. 한쪽만 고치면 정상 행이 손상으로 판정된다(4번과 겹치면 purge도 막힘). runtime은 2744줄이고 CAS 하나(`:1647-1878`)가 콜백 10단 중첩이다.
- 수정 방향: `indexeddb-records.ts`로 모은다.
8. **[권장·확인됨] 삭제 후 재생성 시 revision/generation이 1로 돌아감 (ABA)**
- 위치: `indexeddb-runtime.ts:1693`, `:1955`, `opfs-byte-store-adapter.ts:204`
- 시나리오: 삭제 전에 revision 1을 읽은 writer가 `expectedRevision: 1`로 CAS하면 새 레코드를 덮어쓴다. OPFS도 `open({generation: 1})`이 다른 객체를 돌려줄 수 있다.
- 수정 방향: 마지막 revision을 tombstone으로 남기고 이어서 번호를 매긴다. 의도라면 port 주석에 명시한다.
9. **[사소·확인됨] 보상이 실패하면 put의 원래 실패 원인이 가려짐**
- 위치: `opfs-byte-store-adapter.ts:248-264`
- 시나리오: 사용자 취소(ABORTED)나 쿼터 초과에 ABORT_PUT 보상까지 실패하면 `CONFLICT`/`OBJECT_RECONCILE`만 받는다.
- 수정 방향: 원래 코드를 유지하고 recovery만 `RECONCILE`로 바꾼다.
10. **[사소·확인됨] kernel 계약의 작은 구멍 2개 (현재 걸리는 호출자 없음)**
- `src/adapters/platform/indexeddb-transaction.ts:246-277`: `succeed()` 뒤 `fail(x)`가 오면 x가 버려진다("first failure wins"와 다름).
- `src/adapters/platform/indexeddb-connection.ts:328-359`: caller abort가 upgrade보다 먼저 settle되어도 `onupgradeneeded`가 migration을 커밋한다.
- 수정 방향: `fail`이 성공 후보를 덮어쓰게 하고, `onupgradeneeded` 첫 줄에 `if (settled) { abortUpgrade(); return; }`.
잘 된 점: kernel이 settle-once, 늦은 연결 닫기, 리스너/타이머 정리를 한 곳에서 처리하며 예전 4벌 상태 기계를 대체했다. worker 응답 디코더가 accessor, 미정의 key, kind 불일치를 거절한다. 쿼리 페이지네이션이 "페이지 가득 참"과 "스캔 한도 도달"의 재개 지점을 구분한다.
### 6.6 web-push / service-worker
요약: 업데이트 활성화(페이지 ↔ 대기 워커 메시지)에 막히는 경로가 3개 있다. 첫 방문에 설치 중인 워커를 ACTIVE로 보고한다. Web Push는 입력 검증과 클릭 URL 제한이 튼튼하지만, logout 뒤 해제 실패 시 새 계정을 자동 등록한다.
1. **[필수·가능성(높음)] 활성화 성공 응답을 페이지가 PROTOCOL_MISMATCH로 처리**
- 위치: `src/adapters/service-worker/service-worker-page-controller.ts:334`
- 문제: 워커는 `skipWaiting()` 뒤에 `ACTIVATE_ACCEPTED`/`ACTIVATED_RELOAD_REQUIRED`를 보낸다(`service-worker-lifecycle.ts:292-305`). 이때 `registration.waiting`은 이미 `null`이다. 속성 갱신이 메시지보다 먼저 오면 `registration?.waiting !== waiting` 검사에 걸린다.
- 시나리오: 활성화는 확정됐는데 요청한 탭은 실패로 알고 새로고침하지 않는다. 옛 빌드 코드로 새 워커 아래에서 계속 돈다.
- 확인 방법: 실제 Chromium에서 두 빌드로 업데이트를 돌리는 Playwright 테스트.
- 수정 방향: 확정 이후 메시지는 `registration.active === waiting`도 허용하고, nonce/kind로 먼저 거른 뒤 source를 검사한다.
- 테스트: 성공 경로 테스트 없음. fixture가 `registration.waiting`을 바꾸지 않는다.
2. **[필수·확인됨 ✓] 다른 빌드 탭이 하나라도 있으면 활성화가 항상 30초 타임아웃**
- 위치: `service-worker-lifecycle.ts:364-370`, `:381-395`, `service-worker-page-controller.ts:209-215`
- 문제: 워커가 drain 요청을 `targetBuildId: requesterBuildId`로 보낸다. 페이지는 target이 자기 빌드가 아니면 `TARGET_BUILD_MISMATCH`로 버린다. 워커도 `sourceBuildId !== requesterBuildId` 응답을 무시한다.
- 시나리오: 배포 후 탭 A는 빌드 N, 새로고침한 탭 B는 N+1(navigation이 NETWORK_ONLY라 항상 이렇게 됨). B가 활성화를 요청하면 A가 답하지 않아 30초 뒤 `CLIENT_DRAIN_TIMEOUT`. 반대도 같다. Chrome이 얼린 백그라운드 탭도 활성화를 막는다.
- 수정 방향: requester 빌드 필터를 없애고 워커 자신의 buildId와 nonce로만 짝을 맞춘다.
- 테스트: 없음.
3. **[필수·확인됨] 요청하지 않은 탭은 활성화 뒤에도 새로고침하지 않고, 새 워커는 이전 캐시를 안 씀**
- 위치: `service-worker-page-controller.ts:242`, `service-worker-lifecycle.ts:194-199`, `:220-226`, `src/contracts/service-worker.ts:147-152`
- 문제: 모든 탭에 `ACTIVATED_RELOAD_REQUIRED`를 보내지만 일반 리스너는 `observe()`만 하고, `ServiceWorkerRuntimeHost`에 앱에 알릴 방법이 없다. 새 워커의 `onFetch`는 현재 캐시만 읽는다. 옛 빌드 lazy chunk는 네트워크로 가고 서버에서 지웠으면 ChunkLoadError. `onActivate`가 남긴 이전 캐시는 어디서도 읽지 않고, `void SERVICE_WORKER_BOUNDS.retainedPreviousCaches`(`:199`)는 아무 일도 안 한다. 6시간마다 `registration.update()`로 waiting이 생겨도 앱에 알리는 경로가 없다.
- 수정 방향: host 계약에 `onReloadRequired`/`onUpdateWaiting` 구독을 추가하고, current miss 때 marker로 찾은 previous 캐시를 fallback으로 읽는다.
4. **[필수·확인됨] 첫 방문에서 `start()`가 설치 중인 워커를 `ACTIVE`로 보고**
- 위치: `service-worker-page-controller.ts:183-197`
- 문제: `register()`는 `installing` 상태에서 resolve된다. 첫 방문에는 `active`/`waiting`이 `null`이라 `{kind:"ACTIVE"}`를 돌려준다. 설치가 실패해도(5번) 매 방문 ACTIVE를 보고한다.
- 수정 방향: `installing`이 있으면 `statechange`를 제한 시간 안에서 기다리거나, `!container.controller`면 `RELOAD_TO_ENABLE`/INSTALLING을 반환한다.
- 테스트: fixture가 `installing: null`로 고정.
5. **[필수·가능성] 흔한 서버 설정에서 static 설치가 항상 실패**
- 위치: `service-worker-static-assets.ts:250-256`, `:319-327`
- 문제: content-type을 정확 일치로 비교한다(`.js` → `text/javascript`). `application/javascript`로 응답하는 서버에서 `CONTENT_TYPE_INVALID`. `Content-Encoding: gzip/br` + `Content-Length`(압축 크기)를 압축 해제 크기와 비교해 `BYTES_MISMATCH`.
- 확인 방법: nginx gzip_static 또는 `application/javascript`로 dist를 서빙하고 install이 rejected 되는지 본다.
- 수정 방향: JS MIME 동의어 집합을 쓰고, `content-encoding`이 있으면 Content-Length 비교를 건너뛴다(크기는 스트림 바이트와 sha256으로 이미 검증).
6. **[필수·확인됨 ✓] fetch 핸들러가 모든 요청에 `respondWith` 호출 (성능)**
- 위치: `src/adapters/service-worker/service-worker-entry.ts:92-103`
- 문제: navigation, API, cross-origin까지 `onFetch → fetch(request)`를 거친다. `PWA_STATIC_ASSETS` 없이 WEB_PUSH만 선택해도 그렇다. navigation preload도 꺼져 있어 모든 이동과 API 호출이 "워커 부팅 → 네트워크"로 직렬화된다.
- 수정 방향: GET이고 navigate가 아니고 `runtime.manifestUrls.has(url)`일 때만 `respondWith`를 부른다.
- 테스트: 없음.
7. **[필수·확인됨] logout 뒤 native 구독이 남으면 `reconcile`이 새 계정을 opt-in 없이 자동 등록**
- 위치: `src/adapters/web-push/push-subscription-adapter.ts:345-354`, `:876-880`, `push-association-fence-store.ts:246-256`
- 시나리오: 오프라인 logout → `unsubscribe()` 실패 → fence는 REVOKED, native 구독은 살아 있음 → 사용자 B 부팅 → `reconcile(B)` → 서버 `ABSENT` → `registerAndActivate`. fence store도 REVOKED → 다른 epoch ACTIVE 전환을 허용한다. 설계 문서의 "새 account opt-in은 consent 재평가", "기존 association 재사용 금지"와 어긋난다. 이전에 연기한 WP-04와는 다른 문제다.
- 수정 방향: `ABSENT` 재등록은 local association이 ACTIVE였던 경우(크래시 복구)에만 하고, REVOKED/UNASSOCIATED면 native를 unsubscribe한다.
- 테스트: 없음.
8. **[권장·확인됨] asset 목록이 같은 두 워커 빌드에서 설치가 실패하면 현재 쓰는 캐시를 지움**
- 위치: `service-worker-static-assets.ts:126`, `:150-151`, `scripts/generate-service-worker-assets.ts:89-91`
- 문제: 캐시 이름이 asset 목록 digest로만 정해져 같은 `VITE_BUILD_ID`로 워커만 바뀐 빌드는 active 워커와 같은 캐시에 설치한다. 실패 시 `caches.delete(cacheName)`이 서빙 중인 캐시와 marker를 지운다.
- 수정 방향: 후보 캐시 이름이 active 캐시와 같으면 설치를 건너뛰거나 실패해도 지우지 않는다.
9. **[권장·확인됨] activate가 marker를 쓴 뒤에야 오래된 캐시를 지움**
- 위치: `service-worker-lifecycle.ts:171-198`
- 문제: 공간 부족으로 `currentCache.put(marker)`가 throw하면 삭제 루프가 실행되지 않는다. 공간이 영영 회복되지 않는다.
- 수정 방향: 삭제를 먼저 하고 marker 쓰기는 try/catch로 감싼다.
10. **[권장·확인됨] 활성화 대기 중 관련 없는 메시지로 PROTOCOL_MISMATCH + 페이지·워커 타임아웃 동일**
- 위치: `service-worker-page-controller.ts:317-337`, `:299`
- 문제: `SYNC_WAKE_OBSERVED`(`service-worker-entry.ts:161-166`)나 `CACHE_RESET_RESULT`가 오면 nonce/kind 확인 전에 source 검사에 걸려 실패한다. 두 deadline이 모두 `clientDrainMs`(30초)라 마지막 탭이 29초에 답하면 페이지는 TIMEOUT인데 워커는 `skipWaiting`까지 확정한다.
- 수정 방향: nonce/kind로 먼저 거르고, 페이지 deadline에 여유분을 더한다.
11. **[권장·가능성] push/알림 클릭을 거절할 때 사용자에게 아무것도 보여주지 않음**
- 위치: `src/adapters/web-push/inbound/push-event-adapter.ts:106-150`, `inbound/notification-click-adapter.ts:110-114`, `:163-170`
- 문제: EXPIRED, RELEASE_MISMATCH, fence 읽기 실패, deadline 초과가 알림 없이 끝난다. Chrome은 대신 "This site has been updated in the background"를 띄운다. Safari는 조용한 push가 반복되면 구독을 취소한다고 알려져 있다. 클릭도 `expiresAt`(최대 24시간) 초과나 fence 불일치면 창을 열지 않는다. drop 자체는 설계 의도다.
- 확인 방법: WebKit의 조용한 push 정책 문서 확인.
- 수정 방향: 계정 정보 없는 generic 알림 fallback, 클릭 실패 시 앱 루트 열기. 또는 트레이드오프를 문서에 명시한다.
12. **[사소·확인됨] web-push 중복 helper, 파일 비대, 버려지는 주입값**
- `base64UrlDecode` 2벌: `push-subscription-adapter.ts:1093`(`>>>`), `push-registration-gateway.ts:298`(`>>`), 끝 비트 검증 조건도 다르다.
- `OPAQUE_ID` 3벌: `push-codec.ts:11`, `push-association-fence-store.ts:19`, `push-registration-gateway.ts:9`.
- `validAuthority` 2벌: `push-association-fence-store.ts:668`, `push-registration-gateway.ts:247`(null 방어 없음 → TypeError).
- `push-subscription-adapter.ts` 1139줄.
- `service-worker-page-controller.ts:268`이 전역 `document`를 쓴다. `src/bootstrap/register-service-worker.ts:22`는 `host.document`를 받지만 넘기지 않는다.
- 수정 방향: `web-push/codec-primitives.ts`로 모은다.
잘 된 점: push payload에서 제목·본문·URL을 받지 않고 registry 고정 문구와 same-origin 경로만 쓴다. static 설치의 sha256 검증, 바이트 상한, all-or-nothing, deadline 뒤 정리. 캐시·등록 소유권 판정으로 남의 캐시를 지우는 경로가 없다.
### 6.7 contracts (`src/contracts/`)
요약: 입력 검증 함수 5개가 잘못된 값을 통과시킨다(멱등 키, 설정 키, 매니페스트 URL, REST 명령 메서드, operationId). 모두 에이전트가 node로 재현했다. 스냅샷·exact-key 로직이 모듈마다 달라 두 곳에서 불변식이 깨진다. 레이어 위반은 없고 1000줄 넘는 파일도 없다(최대 `browser-rpc.ts` 979줄).
1. **[필수·확인됨] 멱등 키 검증이 fetch가 잘라내거나 거부할 값을 통과시킴**
- 위치: `src/contracts/mutation-intent.ts:34`
- 문제: `trim()` 후 비어 있지 않은지와 C0/C1 제어문자만 검사한다. 주석은 "never trimmed"라고 한다.
- 시나리오 A: `" order-1 "`가 통과하고 `Headers.set`이 `order-1`로 잘라 보낸다. 서로 다른 두 명령이 같은 키를 갖고 두 번째는 재전송으로 처리되어 적용되지 않는다.
- 시나리오 B: `"키-값"`이 통과하고 `headers.set`이 ByteString TypeError를 던진다. `src/adapters/http/client.ts:772`의 catch가 `NETWORK_UNREACHABLE`(재시도 가능)로 바꾼다.
- 수정 방향: `^[\x21-\x7E]{1,256}$`로 제한한다(`realtime-events.ts:77` `HEADER_SAFE_CURSOR`와 같은 규칙).
- 테스트: `tests/unit/legacy-and-optional-network-remediation.test.ts:136`이 `"키-값"`, `"ключ"`를 유효 키로 고정하고 있다. 함께 고쳐야 한다.
2. **[필수·확인됨 ✓] 설정 키 금지어 검사가 FEATURE_OVERRIDES 안의 기능 ID까지 걸러 킬스위치 사용 시 부팅 실패**
- 위치: `src/contracts/env.ts:73-89`
- 문제: `assertSafeConfigNames`가 중첩 객체 키까지 재귀 검사한다. FEATURE_OVERRIDES의 키는 설정 이름이 아니라 기능 ID(데이터)다. `release-artifacts.ts:67`의 기능 ID 정규식은 `cookie-consent`, `password-reset`, `token-wallet`을 허용한다.
- 시나리오: 장애 중 `{"FEATURE_OVERRIDES":{"cookie-consent":"DISABLED"}}`를 배포하면 `load-runtime-config.ts:110`에서 `CONFIG_SECRET_NAME_REJECTED`가 나고 앱 전체가 부팅되지 않는다.
- 수정 방향: 값을 키로 쓰는 맵은 재귀에서 빼거나, 그런 기능 ID를 빌드 시점에 거부한다.
- 테스트: 없음.
3. **[필수·확인됨] 릴리스 매니페스트 URL의 same-origin 검사를 탭 문자로 우회**
- 위치: `src/contracts/release-artifacts.ts:28`
- 문제: `//` 시작, `?`, `#`, `\`, `%2f`만 검사한다. WHATWG URL 파서는 탭/CR/LF를 지운다. `"/\t/evil.example/m.json"`이 통과해 `https://evil.example/m.json`이 된다. `/a/%2e%2e/b`도 통과 후 `/b`가 된다. 설정은 운영자가 관리해 원격 공격 경로는 아니지만 검증 약속이 깨져 있다.
- 수정 방향: `new URL(v, "https://x.invalid")`로 해석해 origin 유지와 `pathname === v`를 확인하거나, `^/[A-Za-z0-9._~/-]+$` 허용 목록.
- 테스트: `tests/runtime-schema/runtime-config.test.ts:49-54`는 `..`와 `?`만.
4. **[필수·확인됨] REST V2가 COMMAND를 GET으로 허용하고 CSRF 필요 여부는 메서드로만 판단**
- 위치: `src/contracts/api-operations.ts:182`, `src/contracts/rest-profiles.ts:240`
- 문제: `validateRestOperation`은 QUERY가 GET/HEAD인지만 보고, `semantics`/`replayPolicy` enum도 검증하지 않는다. `resolveRestSecurityProfiles`는 `unsafe`를 메서드로만 정한다. `{semantics:"COMMAND", method:"GET"}` + SAME_ORIGIN_COOKIE + csrf NONE이 통과한다. browser-rpc(`browser-rpc.ts:652-666`)와 V3(`external-contract-runtime.ts:448-469`)는 이 규칙을 강제한다. 지금 설치된 쿠키 프로필이 없어 잠재 결함이다.
- 수정 방향: COMMAND면 POST/PUT/PATCH/DELETE만 허용하고 enum을 검증한다.
- 테스트: 없음.
5. **[필수·확인됨] operationId 형식이 4곳에서 달라 API 실패 텔레메트리가 드롭됨**
- 위치: `src/contracts/telemetry.ts:111`, `src/contracts/external-contract-runtime.ts:237`
- 문제: V3 합성은 `^[A-Za-z][A-Za-z0-9_.-]{0,127}$`(camelCase 허용), 텔레메트리 `operation_id`는 `^[A-Z][A-Z0-9_]{0,63}$`다. `api.request.failed`가 `invalid-attribute-value`로 떨어지고 `best-effort-telemetry.ts:162`에서 drop된다. diagnostics `SAFE_VALUE`(`diagnostics.ts:123`)는 64자 제한이다. `api-operations.ts:54`, `browser-rpc.ts:185`는 `{2,79}`다. `http_status_group`도 diagnostics `[0-9]xx`, 텔레메트리 `[1-5]xx`로 다르다.
- 수정 방향: OPERATION_ID를 contracts에 하나만 두고 재사용한다.
6. **[권장·확인됨] 스냅샷 불변식이 모듈마다 달라 두 곳에서 뚫림**
- (a) `external-contract-runtime.ts:751` vs `:770`: TEMPLATE_FIXTURE의 이벤트 기여 금지 검사는 `.length`로, 설치는 iterator로 한다. 배열에 `Symbol.iterator`를 달면 길이 0으로 통과 후 이벤트가 설치된다. `exact-snapshot.ts:154`의 `snapshotExactArray`를 쓰지 않는다.
- (b) `realtime-streams.ts:529` `hasExactKeys`가 `Object.keys`만 봐서 getter를 허용하고, 검증과 `{...input}` 복사에서 두 번 읽는다(`:465-486`). getter로 `maxEventBytes` 999,999,999가 설치된다(하드 상한 65,536).
- exact-key 구현 6곳: `exact-snapshot.ts:66`, `read-only-registry.ts:54`(try/catch 없음), `browser-rpc.ts:399`(enumerable 미검사), `realtime-streams.ts:529`, `cache-invalidation.ts:208`, `service-worker-static-manifest.ts:98`.
- 입력이 컴파일 시점 코드라 권장으로 분류했다.
- 수정 방향: `exact-snapshot.ts`로 통일하고 배열 스냅샷을 추가한다.
- 테스트: `tests/unit/contract-registry-immutability.test.ts`는 객체 단위만.
7. **[권장·확인됨] 검증된 인덱스/레지스트리가 수정 가능한 상태로 반환됨**
- 위치: `src/contracts/query-invalidation.ts:185`, `:232`, `web-worker.ts:138`, `offline-command.ts:152`, `runtime-capabilities.ts:199`
- 문제: `Object.freeze({ namespacesForTopic: new Map(...) })`는 바깥만 얼린다. `.clear()`가 동작한다. 나머지는 바깥 배열만 얼려 내부 상한값 객체를 바꿀 수 있다. `read-only-registry.ts` 주석(LIVE-02)이 바로 이 버그를 설명한다.
- 수정 방향: `createReadOnlyRegistry`를 쓰고 각 row를 스냅샷해 얼린다.
8. **[권장·확인됨] 같은 개념이 두 모양: 검증기 프로토콜 2개, `MappingResult` 2개**
- `RuntimeValidator.safeParse`(`external-contract-runtime.ts:43-50`, path 배열) vs `RuntimeSchemaCodec.parse`(`schema-registry.ts:18-28`, path 문자열). reference feature가 zod 래퍼를 두 번 쓴다(`reference-feature-contract-contribution.ts:34`, `:88`).
- `MappingResult`: `boundary-mapper.ts:6` `{ok:false, code}` vs `external-contract-runtime.ts:84` `{ok:false, error:{kind, code}}`. 잘못 import해도 컴파일된다.
- 수정 방향: 각각 하나로 합친다.
9. **[권장·확인됨] 인증 프로필 기준 원본이 둘로 갈림**
- 위치: `external-contract-runtime.ts:337`, `rest-profiles.ts:235`
- 문제: 합성은 모듈 전역 `INSTALLED_REST_AUTH_PROFILES`, 실행기는 주입된 `dependencies.authProfiles`(`http-execution-v3.ts:413`)를 쓴다. V2 클라이언트는 검증 안 된 `REST_AUTH_PROFILES`를 직접 쓴다(`client.ts:565`). BEARER_HEADER + `credentials:"same-origin"`이 install에서는 거부되지만 resolve에서는 통과한다.
- 수정 방향: resolve가 `InstalledRestAuthProfiles`를 받게 하고 합성은 레지스트리를 매개변수로 받는다.
10. **[권장·확인됨] 배포 승인이 IPv6·사설 대역 호스트를 공개 주소로 봄**
- 위치: `src/contracts/deployment-admission.ts:139`
- 문제: `https://[::ffff:127.0.0.1]/`, `[fd00::1]`, `[fe80::1]`, `100.64.0.1`, `0.1.2.3`, `api.internal`이 production 승인을 받는다. 로컬 호스트 목록이 3곳에 따로 있다(`browser-rpc.ts:780`, `rest-profiles.ts`, 이 파일).
- 테스트: IPv4 사설 대역만(`tests/unit/deployment-admission.test.ts:67-68`).
11. **[사소·확인됨] 레지스트리 조회가 프로토타입 체인까지 내려감**
- `getApiOperation("constructor")`가 `Object` 함수를 반환(`api-operations.ts:203`).
- `getStorageDefinition("__proto__")`가 `Object.prototype`을 반환(`storage-keys.ts:162`).
- `isAllowedOfflineTransition`이 모르는 상태에 TypeError를 던짐(`offline-command.ts:102`). false가 맞다.
- 지금 호출자는 상수만 넘긴다. 수정: `Object.hasOwn`.
12. **[사소·확인됨] 조용한 통과와 자잘한 문제**
- `release-tokens.ts:62`: runtime 쪽 `assetManifestHash`를 release 자신의 값으로 채워 비교가 항상 일치한다. "비교 안 함"이 아니라 "통과"로 나온다.
- `contract-set.ts:119`: `expected`에 packageId 중복 + `expectedSetDigest` 없음이면 예외가 나서 Promise가 reject된다.
- `query-keys.ts:217`: 새 identity intern마다 전체 row 복사·정렬(O(n log n), n ≤ 4096).
- `.dependency-cruiser.json`은 contracts → presentation/bootstrap 방향을 막지 않는다(현재 위반은 없음).
잘 된 점: `contract-set-canonical.ts`의 정규화(길이 접두, UTF-8 바이트 정렬, 중복 거부). `realtime-events.ts`의 시퀀스(BigInt 상한)·타임스탬프 검증, `cache-invalidation.ts`의 크기·TTL·clock skew 제한. `read-only-registry.ts`의 Map 불변 처리.
### 6.8 presentation (`src/presentation/`)
요약: adapter 직접 import, `any`, `@ts-ignore`, `dangerouslySetInnerHTML`은 없다. 버그는 라우팅에 몰려 있다. React Router가 형제 라우트의 컴포넌트 인스턴스를 재사용하는 점, route-change 부수효과(포커스·제목·텔레메트리)의 위치에서 청크 복구 고착, 로케일 초기화, 포커스 버그가 나온다. 상태 화면과 세션 액션이 여러 벌이다.
1. **[필수·확인됨 ✓] 청크 복구 실패 화면이 다른 라우트로 이동해도 풀리지 않음**
- 위치: `src/presentation/boundaries/chunk-recovery-boundary.tsx:38-84`, `src/presentation/routes/app-router.tsx:316-326`
- 문제: React Router 7.18은 `RenderedRoute`에 key를 붙이지 않아 형제 라우트 이동 시 `ChunkRecoveryBoundary`까지 같은 인스턴스가 재사용된다. boundary에 resetKey/key가 없어 `error`/`support` 상태가 남는다. 실패 화면(`:109-114`)에 재시도·새로고침 버튼이 없다.
- 시나리오: 오프라인에서 아직 안 받은 `/examples/states`로 이동 → 청크 실패 → `manifest-unavailable`로 `support` → 메모리에 있는 홈으로 돌아가도 "화면 자산을 복구하지 못했습니다"가 계속 보인다. 브라우저 새로고침만이 탈출구다.
- 수정 방향: `<ChunkRecoveryBoundary key={definition.routeId} …>` 또는 resetKey + `componentDidUpdate`. 실패 화면에 `action.reloadOnce` 버튼.
- 테스트: `tests/component/chunk-recovery-boundary.test.tsx`에 리셋 케이스 없음.
2. **[필수·확인됨] Safari와 Vite CSS preload 실패를 청크 실패로 인식하지 못함**
- 위치: `chunk-recovery-boundary.tsx:27-36`
- 문제: 판별 문자열에 WebKit `"Importing a module script failed."`와 Vite `"Unable to preload CSS for …"`가 없다. Safari 사용자는 배포 뒤 옛 청크 요청 시 일반 렌더 오류로 분류되어 reload-once 복구가 실행되지 않는다.
- 수정 방향: 두 문자열을 추가하고, bootstrap에서 `vite:preloadError`도 받는다.
- 테스트: Chrome 메시지 하나만.
3. **[필수·확인됨] 로케일이 저장되지 않고 세션이 바뀔 때마다 ko-KR로 초기화**
- 위치: `src/presentation/i18n/locale-provider.tsx:76`, `:81`, `app-router.tsx:497`, `src/presentation/adapters/query/server-state-scope-provider.tsx:31-35`
- 문제: 로케일이 `useState`에만 있고 preferences 포트에 locale 항목이 없다(테마는 `preferences.setColorScheme`으로 저장됨). `LocaleProvider`는 `AppRouter` 안, `AppRouter`는 `ServerStateScopeProvider` 아래에 있다. 세션 알림 → scope `FENCED`(`server-state-scope-runtime.ts:90-104`) → transitionFallback 렌더로 앱 트리 전체 unmount → `READY`에서 `ko-KR`로 다시 mount된다.
- 시나리오: en-US를 고르고 로그인/로그아웃하면 한국어로 돌아간다.
- 같은 remount의 추가 영향: 작성 중 폼 입력이 dirty guard 없이 사라진다(가능성, auth owner의 알림 빈도에 따름). `AppRouter:489`의 `useMemo` browser router가 `dispose()`되지 않아 remount마다 popstate 리스너가 쌓인다.
- 수정 방향: locale을 preferences 포트로 저장하고, Locale/Theme provider를 scope fence 바깥(bootstrap)으로 올리고, unmount 시 `router.dispose()`.
- 테스트: `tests/e2e/i18n.spec.ts`, `tests/component/locale-platform.test.tsx`에 저장·세션 전환 케이스 없음.
4. **[필수·확인됨] 언어를 바꾸면 포커스 이동, 맨 위 스크롤, route 변경 재보고**
- 위치: `app-router.tsx:145-171`
- 문제: `RouteLifecycle` effect 의존성에 `message`/`resolve`가 있고, 이 둘이 locale 변경마다 새로 만들어진다(`locale-provider.tsx:108`). `docs/architecture/routing-pages-and-patterns.md:467`의 "locale 변경은 title과 copy만 다시 렌더" 계약과 어긋난다.
- 가능성: `location.key` 의존 때문에 해시만 바뀌는 이동(스킵 링크, `ErrorSummary`의 `#field`)에서도 다시 실행될 수 있다. 브라우저 확인 필요.
- 수정 방향: 제목 effect(locale 의존)와 포커스·스크롤·텔레메트리 effect(`pathname`+`search` 의존)를 나눈다.
- 테스트: 없음.
5. **[필수·확인됨] 인증필요·잘못된 주소·비활성 기능 화면에서 제목·포커스·텔레메트리가 동작하지 않음**
- 위치: `app-router.tsx:304-314`, `:316-335`
- 문제: `RouteLifecycle`이 `content` 안에만 있는데 `ProtectedRoute`, `InvalidRouteSurface`, `DisabledFeatureSurface`는 `content`를 렌더하지 않는다.
- 시나리오: 익명 상태에서 reference 라우트에 들어가면 `document.title`이 이전 페이지 그대로이고, 포커스가 NavLink에 남아 스크린리더 사용자는 페이지가 바뀐 것을 모른다. 텔레메트리도 빠진다.
- 수정 방향: `RouteLifecycle`을 `RegisteredRoute` 최상단으로 올린다.
6. **[필수·확인됨] 모바일 드로어로 이동하면 포커스가 햄버거 버튼으로 감**
- 위치: `src/presentation/layouts/app-shell.tsx:44-46`, `:153-161`, `src/presentation/design-system/primitives/core.tsx:374-391`
- 문제: 자식 effect `RouteLifecycle`이 `main.focus()`를 먼저 부르지만 modal이 열려 있어 main이 inert다. 부모 effect가 드로어를 닫고, `Dialog`가 `setTimeout`으로 `returnFocusRef`(메뉴 버튼)에 포커스를 복원한다. 데스크톱은 h1이 포커스를 받는다.
- 수정 방향: 네비게이션으로 닫힐 때는 포커스 복원을 끄거나, route 포커스를 dialog 닫힘 뒤로 미룬다.
- 테스트: `tests/e2e/app-shell.spec.ts`는 Escape 닫기만.
7. **[필수·확인됨] context 라우트 게이트웨이가 이전 context의 routes로 한 번 렌더되고 청크 실패 복구를 거치지 않음**
- 위치: `app-router.tsx:375-419`
- 문제 (a): `ContextRouteGateway`도 key 없이 재사용된다. context A → B 이동 첫 렌더에서 A의 routes로 B 경로를 매칭해 `NOT_FOUND`가 mount되고 텔레메트리·제목·포커스가 한 번 튄다. 지금은 context가 하나라 드러나지 않지만 하나 더 추가하면 바로 발생한다.
- 문제 (b): `loadRoutes()`의 dynamic import 실패 시 `RouteFailureSurface`만 보이고 `recoverChunk`(reload-once)를 거치지 않는다. 도메인 확장의 주 경로가 배포 직후 청크 실패 복구에서 빠져 있다.
- 수정 방향: `key={routeModule.id}` 또는 `{moduleId, routes}` 상태. 로드 실패는 `isChunkLoadFailure`로 판별해 `recoverChunk`로 넘긴다.
8. **[필수·확인됨 ✓] `useApplicationQuery({enabled:false})`가 영원히 로딩으로 보임**
- 위치: `src/presentation/adapters/query/application-query.ts:180`
- 문제: TanStack Query v5에서 데이터 없는 disabled 쿼리는 `isPending=true`(fetchStatus `idle`)다. `isInitialLoading: query.isPending`을 그대로 넘긴다.
- 시나리오: 선행 값을 기다리는 의존 쿼리가 `AsyncSurface`에서 계속 스켈레톤과 `aria-busy`를 보여준다.
- 수정 방향: `query.isLoading`(isPending && isFetching)을 넘긴다.
- 테스트: `enabled` 케이스 없음.
9. **[권장·확인됨] 디자인시스템 링크가 router와 basename을 우회**
- 위치: `src/presentation/templates/page-templates.tsx:247-254`, `design-system/primitives/navigation.tsx:24`, `:178`, `core.tsx:78-105`
- 문제: `PageActionBar` link, `Breadcrumbs`, `LinkButton`이 모두 `<a href>`다. `routerBasePath`가 `/`가 아닌 배포에서 basename이 빠진 URL로 이동하고, 전체 리로드로 query cache와 UI 상태가 날아간다. `Pagination`의 `href="?page=N"`은 다른 검색 파라미터를 지운다.
- 수정 방향: `to`를 받아 `Link`로 렌더한다.
10. **[권장·확인됨] 상태 화면과 세션 액션이 여러 벌**
- 로딩: `components/async-surface.tsx:9`, `app-router.tsx:64`, `app-router.tsx:407-413`(라벨 없음), `chunk-recovery-boundary.tsx:96`, `pages/home-page.tsx:29-37`과 `examples/platform-overview-page.tsx:287-295`(`.catch` 없어 reject 시 멈춤).
- 인증필요: `ProtectedRoute`(`app-router.tsx:243-273`), `AuthRequiredSurface`(`state-surfaces.tsx:31`), `StatusPage variant="unauthenticated"`.
- 404: `NotFoundPage`, `NotFoundSurface`, `StatusPage`.
- 세션 액션: `app-shell.tsx:48`, `app-router.tsx:213`, `auth-example-page.tsx:13`(세 번째만 `returnTo`에서 hash 누락).
- 수정 방향: route 레벨도 `LoadingSurface`/`StatusPage` 하나로, 세션 액션은 hook 하나로.
11. **[권장·확인됨] Tooltip 설명이 보조기술에 전달되지 않음**
- 위치: `src/presentation/design-system/primitives/overlays.tsx:114`
- 문제: `aria-describedby`가 포커스 안 받는 wrapper `<span>`에 붙어 있다. 내용이 항상 DOM에 있고 opacity만 0이다. Escape로 닫을 수 없다(WCAG 1.4.13).
- 수정 방향: `cloneElement`로 자식에 `aria-describedby`를 주입하고 Escape 닫기를 추가한다.
- 테스트: 없음.
12. **[권장·확인됨] Pagination이 페이지 수만큼 링크를 전부 렌더**
- 위치: `design-system/primitives/navigation.tsx:160`
- 문제: `pageCount=5000`이면 링크 5000개, Tab 이동이 사실상 불가능하다. `CollectionPage`의 `<nav>` 안에 `Pagination`의 `<nav>`가 중첩된다.
- 수정 방향: 현재 페이지 주변 + 처음/끝만 보여주는 windowing.
13. **[사소/가능성] 기타**
- `routes/platform-route-codecs.ts:4`: `none` 코덱이 `.strict()`라 `/?utm_source=x`나 OAuth 콜백 파라미터가 "잘못된 주소"가 된다. 정책 문서는 "보존 또는 제거를 선언"하라고 한다.
- `forms/use-app-form.ts:176-205`(가능성): `pendingRef`가 `await schema.safeParseAsync` 뒤에 설정되어 비동기 refine이 있으면 두 번 제출될 수 있다.
- `use-dirty-navigation-guard.tsx:9`(가능성): `useBlocker(when)`이 마지막 commit 시점 값을 써서 저장 직후 `navigate()`에 "저장하지 않은 변경" 다이얼로그가 뜬다.
- `render-error-boundary.tsx:55-57`, `message-contract.ts:75`: 기본 fallback이 ko-KR로 고정.
- `forms.tsx:399-402`: SearchField 지우기 버튼 unmount로 포커스가 body로 빠진다.
- `styles/theme.css` 1435줄.
잘 된 점: `useApplicationMutation`의 unknown effect 채널, scope fence, 낙관적 레이어와 컴포넌트 테스트 3개. `Dialog`의 native `<dialog>` + `showModal`과 세대 번호 포커스 복원, `ErrorSummary`의 첫 오류 필드 포커스. `route-codecs`가 cast 없이 zod parse 후에만 사용하고, `SafeText`로 HTML 해석을 차단한다.
### 6.9 application / features / bootstrap / platform (+ apps, contexts)
요약: 레이어 방향은 지켜진다(application은 contracts/ports만 import, platform → apps는 dependency-cruiser 예외). 부트 JSON 리더와 트래픽 budget lease 반환은 정확하다. 버그는 부트 reload 무한 반복, 텔레메트리 횟수, 리댁션이다. 세 건 모두 에이전트가 `node --experimental-strip-types`로 재현했다.
1. **[필수·확인됨 ✓] 부트 mismatch reload가 키가 번갈아 바뀌면 무한 반복**
- 위치: `src/platform/release/release-mismatch-recovery.ts:52-66`, `src/bootstrap/boot-release-recovery.ts:29-37`
- 문제: 마커는 하나이고 이전 키와 **같은 키**일 때만 reload를 막는다. 키가 `buildId:code:releaseId`라서 로드밸런서가 R10/R11을 번갈아 주면 A→B→A→B로 바뀌고 매번 새 키로 판정된다. 시뮬레이션에서 번갈아 20번 부트하면 reload 20번. 주석의 "a persistently mixed deployment cannot loop"는 사실이 아니다.
- 수정 방향: TTL 안에 마커가 있으면 키와 무관하게 `show-failure`. 세션당 자동 reload 최대 1회.
- 테스트: `tests/release/mixed-replica.test.ts:94`는 같은 키만, `release-mismatch-recovery.test.ts:64`는 다른 키면 연속 reload하는 동작을 기대값으로 고정하고 있다.
2. **[필수·확인됨] 텔레메트리 `occurrences`가 운영에서 사실상 항상 1**
- 위치: `src/platform/telemetry/telemetry-pipeline.ts:165`, `:182`, `:229`
- 문제: 기본 스케줄이 `queueMicrotask`라 첫 이벤트가 바로 전송되고 그때 count는 1이다. 60초 dedup 창 안의 중복은 `counters.deduplicated`만 올리고 보고되지 않는다. 같은 error 1000번 emit → 전송 1건, occurrences 1. 버퍼에서 드롭된 이벤트도 fingerprint가 dedup에 남아 60초 동안 전송되지 않는다.
- 수정 방향: 창이 닫힐 때나 다음 flush에서 누적 count를 요약 이벤트로 보낸다.
- 테스트: `tests/platform/telemetry/telemetry-pipeline.test.ts:93`이 `schedule: () => {}`로 자동 flush를 꺼서 25를 기대한다. 운영 경로 미검증.
3. **[필수·확인됨] 리댁션이 키 이름 deny-list와 "문자열 시작" 정규식에만 의존**
- 위치: `src/platform/telemetry/redact-telemetry.ts:31`, `:51`
- 문제: `SECRET_VALUE`가 `^`로 고정되어 `"request failed: Authorization: Bearer abc"`처럼 중간의 자격증명을 못 잡는다. URL 쿼리(`?access_token=...`)도 통과한다. 키 목록에 `pwd`, `pass`, `auth`, `otp`, `pin`이 없고 이메일 처리가 없다. 실측에서 다섯 값이 모두 원문 그대로 나왔다. reference-feature는 enum만 보내 당장 유출은 없지만 payload가 `unknown`인 공용 파이프라인이다.
- 수정 방향: 앵커 제거, URL 쿼리 제거, 이메일 마스킹, 키 목록 보강. 더 안전하게는 feature별 payload allow-list.
4. **[권장·확인됨] 텔레메트리 파이프라인 두 벌**
- 위치: `src/bootstrap/runtime-adapters.ts:303`, `:528`, `src/platform/telemetry/telemetry-pipeline.ts:146`, `src/adapters/telemetry/best-effort-telemetry.ts:176`
- 문제: 같은 `TELEMETRY_ENDPOINT`로 따로 보낸다. 분당 한도 합계 40, body 스키마·credentials 다름, feature 쪽은 `pagehide` flush·`onDrop` 진단·dispose abort가 없다.
- 수정 방향: 전송 계층 하나, port는 projection만 다르게.
5. **[권장·확인됨] 킬스위치(`FEATURE_OVERRIDES`)가 feature input 생성에 적용되지 않음**
- 위치: `src/features/installed-feature-adapters.ts:25`, `src/bootstrap/runtime-adapters.ts:423`, `:540`
- 문제: `composeFeatureAdapterInputs`에 설치된 ID 전체를 넘긴다. 같은 함수에서 `activeFeatureIds`를 계산하고도 안 쓴다. disabled feature도 `application.features.get()`이 API를 준다. 막는 곳은 라우터(`app-router.tsx:304`)뿐이다.
- 수정 방향: active ID를 넘긴다.
- 테스트: `tests/component/product-feature-switch.test.tsx`는 라우트만.
6. **[권장·확인됨] adapter contribution의 featureId 중복·불일치가 조용히 덮어씀**
- 위치: `src/features/feature-adapter-contribution.ts:166`, `:175`
- 시나리오: reference-feature를 복사해 새 feature를 만들며 featureId를 안 바꾸면 `features.get("reference-feature")`가 다른 구현을 반환한다. route codec과 메시지 카탈로그는 중복이면 throw하는데 여기만 없다.
- 수정 방향: `Object.hasOwn` 중복 검사, `installed.featureId !== contribution.featureId`면 throw.
7. **[권장·확인됨(현재 잠재)] 정상 종료한 interaction이 부모 signal에 abort listener를 남김**
- 위치: `src/platform/execution/execution-context.ts:102-108`
- 문제: 완료/dispose API가 없어 오래 사는 signal을 부모로 주면 interaction마다 listener와 AbortController가 쌓인다. 지금은 `signal`을 넘기는 호출자가 없다(`http-execution-v3.ts:455`).
- 수정 방향: `dispose()`/`complete()` 추가 또는 `AbortSignal.any([parent, own])`.
8. **[권장·확인됨] 부트 완료까지 최대 약 10초 빈 화면**
- 위치: `src/bootstrap/main.tsx:27`, `:33`, `index.html`
- 문제: config(5초) → manifest(5초) → contract set 검증 뒤에야 첫 render. `#root`는 비어 있고 `aria-busy`도 없다.
- 수정 방향: `index.html`에 정적 boot shell을 넣거나 await 전에 로딩 surface를 render한다.
9. **[사소·확인됨] "한 번만 reload" 로직 두 벌**
- 위치: `src/application/use-cases/decide-chunk-recovery.ts:35-46` vs `src/platform/release/release-mismatch-recovery.ts`
- 문제: chunk 쪽은 키 `a/b->c/d`, TTL 없음, 마커 안 지움. boot 쪽은 키 `a:code:b`, TTL 10분, 정상 부트 시 삭제. 한쪽을 고쳐도 다른 쪽은 남는다.
- 수정 방향: 공용 guard 하나로.
10. **[사소·확인됨] 검증 실패 config 원본 값이 "safe" 에러에 실려 화면·진단에 나감**
- 위치: `src/bootstrap/load-runtime-config.ts:122-127`
- 문제: `CONFIG_SCHEMA_INVALID` 때 미검증 `RELEASE_ID`/`CONFIG_SCHEMA_VERSION`(최대 64KB)이 BootErrorShell과 진단에 들어간다. React escape로 XSS는 아니지만 파일 상단 주석의 "never carries a validation value"와 어긋난다.
- 수정 방향: 검사를 통과한 값만 넣는다.
11. **[사소·확인됨] 버퍼가 낮은 severity를 지운 뒤 들어온 이벤트도 버림**
- 위치: `src/platform/telemetry/telemetry-buffer.ts:91-103`
- 예: maxBytes 300, info 50 + error 240 상태에서 warning 100 → info를 지워도 공간이 부족해 warning도 드롭. 주석("incoming이 더 중요하지 않으면 드롭")과 달리 같은 severity면 가장 오래된 항목을 지운다.
- 수정 방향: 필요 공간을 먼저 계산해 들어갈 수 있을 때만 지운다.
12. **[사소·확인됨] 구조 정리**
- `src/features/reference-feature/presentation/reference-feature-runtime.tsx`는 같은 이름 `.ts`의 re-export만 한다. 확장자 없는 import가 모호해진다.
- `src/application/policies/promotion-readiness.ts`, `performance-budgets.ts`는 CI 스크립트만 쓰는 로직인데 런타임 application 레이어에 있다.
- `src/features/installed-feature-messages.ts`의 로케일이 `ko-KR`/`en-US`로 하드코딩되어 다른 로케일 카탈로그가 조용히 빠진다.
잘 된 점: `read-bounded-boot-json.ts`가 크기 선확인, fatal UTF-8, 타임아웃과 외부 abort를 한 함수에서 처리한다. 릴리스 identity 비교를 `checkReleaseCoherence` 하나로 모았다. `concurrency-budget`의 멱등 lease 반환과 abort된 waiter 제거가 정확하다.
## 7. 이 리뷰의 한계
- **✓ 재확인** 12건과 6.0을 뺀 나머지는 에이전트 보고다. 일부는 에이전트가 scratchpad node 스크립트로 재현했지만 그 스크립트는 레포에 남기지 않았다.
- "가능성" 항목 중 다수(6.1-6/7/8, 6.2-7/8, 6.5-2, 6.6-1/5/11, 6.8-4 일부, 6.8-13)는 실제 브라우저, 탭 2개 이상, 실제 CDN/서버 설정이 있어야 확인된다.
- `dev`, `build`, e2e, browser-capabilities 테스트는 실행하지 않았다.
- `src/` 밖(`scripts/`, `tests/`, `recipes/`, 설정 파일)은 범위 밖이다. 6.0은 원인이 `src/`의 import라서 포함했다.
- 영역당 발견 수를 약 12건으로 제한했으므로 모든 결함을 망라한 목록은 아니다.
@@ -67,6 +67,7 @@ All 24 files below were read in full.
| src/adapters/http/request-builder.ts | Legacy path/query construction and origin/base-prefix checks | legacy client; ApiOperation | Keep while V2 remains. Do not reuse it to weaken V3 descriptor projection. |
| src/adapters/http/resource-mapper.ts | Thin legacy operation-payload mapper delegation | boundary-mapper; legacy client | No standalone defect. Remove only with V2, not as part of the correctness patch. |
| src/adapters/http/retry-policy.ts | Legacy retry decision/backoff plus parseRetryAfter reused by V3 | legacy client and V3 executor | Keep deterministic parse/backoff seam. V2 must additionally prove a valid key before keyed replay. |
| src/adapters/http/platform-error-mapping.ts | Maps feature-less V3 transport outcomes (cancel, timeout, network, response-invalid) to the platform AppError envelope; feature-owned outcomes return null | http-execution-v3.ts outcomes; platform/errors; feature HTTP binding | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row). |
| src/adapters/http/schema-registry.ts | Legacy Zod envelope/request/payload validation and clone | legacy client/tests | No standalone defect. Remains V2-only and should not be merged with installed external validators. |
| src/adapters/platform/browser-lifecycle.ts | Single owner of visibility/network/focus/page/beforeunload listeners and lifecycle snapshots | optional-runtime-host.ts | Preserve centralized listener ownership and idempotent dispose. Clarify or redesign dirty-source attachment semantics; selection item O-02. |
| src/adapters/platform/browser-mutation-intent-factory.ts | Secure intent/idempotency UUIDs plus monotonic creation time, normalized by defineMutationIntent | MutationIntentFactory port; bootstrap | Keep. Share one idempotency-key validator so external inputs and generated values have identical bounds. |
@@ -77,6 +78,7 @@ All 24 files below were read in full.
| src/adapters/query-cache/tanstack-cache-coordinator.ts | Maps registry topics to query namespace invalidation, coalesces remote hints, defers under mutation leases, resets/disposes | TanStack Query, invalidation contracts, cross-context runtime | Keep invalidate-only remote authority, generation guard, reset serialization and bounded registry validation. Add teardown characterization if dispose becomes async. |
| src/adapters/query-cache/tanstack-query-cache.ts | Creates QueryClient defaults and QueryCachePort read/write/invalidate adapter with diagnostics | TanStack Query, QueryCachePort, errors/diagnostics | Keep retry disabled and clone-on-write. Clone-on-read is an optional port-semantics decision, not a confirmed production defect. |
| src/adapters/telemetry/best-effort-telemetry.ts | Allowlisted bounded oldest-drop telemetry queue, scheduled/pagehide flush, sink isolation and evidence | TelemetryPort, telemetry/diagnostic contracts, bootstrap | Add terminal lifecycle state, joined flush promise and in-flight abort; ensure runtime composition disposes it. |
| src/adapters/telemetry/feature-telemetry.ts | Feature TelemetryPort adapter over the platform telemetry pipeline; fetch transport to the collector endpoint | platform/telemetry pipeline; TelemetryPort; bootstrap | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row); shares the collector with best-effort-telemetry (review 6.9-4). |
## 4. Traced boundary inventory
@@ -79,6 +79,7 @@
| `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | logical object/journal/budget/chunk refcount의 IDB authority; begin/files-ready/commit/rollback/reconcile pages | OPFS ports, IDB failure, policy. journal+object+budget CAS atomicity가 좋다. STO-01 수정에서 incomplete row를 cleanup 확인 전 삭제하지 않아야 한다. |
| `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | logical journal과 physical worker를 saga로 조정, put/open/remove, reconcile/policy maintenance | OPFS/shared ports, journal, worker gateway, policy. STO-01의 journal/physical compensation ordering 결함 위치. |
| `src/adapters/storage/opfs/opfs-policy.ts` | root/lock/chunk/object/RPC/reconcile/GC hard limits 및 scope validation | shared/opfs ports. opaque physical path와 absolute caps 유지. |
| `src/adapters/storage/opfs/opfs-prepared-object.ts` | page·journal·worker가 함께 쓰는 prepared-object 검증기 하나 | OPFS/shared ports, opfs-policy scope 검증. R-5.5: 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증하고 현재 정책값은 새 쓰기에만 적용. |
| `src/adapters/storage/opfs/opfs-worker-client.ts` | request correlation/timeout/abort/transferable chunking, worker gateway, streamed reads | protocol/policy/shared Result. STO-01의 untracked abort cleanup 및 STO-07의 shallow response parse. |
| `src/adapters/storage/opfs/opfs-worker-protocol.ts` | page↔DedicatedWorker request/response union 및 gateway contract | OPFS/shared ports. STO-07; protocol version/kind/effect certainty 추가 필요. |
| `src/adapters/storage/opfs/opfs-worker-runtime.ts` | DedicatedWorker OPFS physical layout, lock lease, immutable chunk, manifest/staging receipt, abort/finalize/remove/GC | protocol/policy/OPFS ports/Web Lock/Crypto. STO-01의 generation-only cleanup과 lease release 순서. sync handle `finally close` 등은 유지. |
+78 -75
View File
@@ -67,80 +67,83 @@
| 57 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 80 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 81 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 82 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 83 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 97 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 98 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 99 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 100 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 104 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 105 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 106 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 107 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 122 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 123 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 124 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 125 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 126 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 127 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 128 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 129 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 130 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 60 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 81 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 82 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 83 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 98 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 99 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 100 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 104 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 105 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 106 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 107 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 124 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 125 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 126 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 127 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 128 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 129 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 130 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 134 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
합계: **133/133**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **136/136**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
+51 -51
View File
@@ -9,26 +9,26 @@
"pnpm": ">=11.0.0 <12.0.0"
},
"scripts": {
"dev": "vite",
"build": "node scripts/build-frontend.ts",
"dev": "node scripts/generate-product-feature-index.ts && vite",
"build": "node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts",
"build:profile": "node scripts/generate-runtime-config.ts",
"build:release-candidate": "corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security && corepack pnpm verify:release && node scripts/verify-supply-chain-artifacts.ts && node scripts/create-release-candidate.ts",
"build:release-candidate": "node scripts/generate-product-feature-index.ts && corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security && corepack pnpm verify:release && node scripts/verify-supply-chain-artifacts.ts && node scripts/create-release-candidate.ts",
"preview": "vite preview",
"lint": "eslint src scripts tests recipes .storybook vite.config.ts vitest.config.ts playwright*.config.ts --max-warnings=0",
"check:architecture": "node scripts/check-architecture.ts",
"check:design-system": "node scripts/check-design-system.ts",
"check:design-system:fixture": "node scripts/check-design-system.ts --fixture",
"check:i18n": "node scripts/check-i18n.ts",
"check:i18n:fixture": "node scripts/check-i18n.ts --fixture",
"check:architecture": "node scripts/generate-product-feature-index.ts && node scripts/check-architecture.ts",
"check:design-system": "node scripts/generate-product-feature-index.ts && node scripts/check-design-system.ts",
"check:design-system:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-design-system.ts --fixture",
"check:i18n": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts",
"check:i18n:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts --fixture",
"check:adapter-inventory": "node scripts/check-adapter-inventory.ts",
"check:remediation-ledger": "node scripts/check-remediation-ledger.ts",
"check:release-admission": "node scripts/check-release-admission.ts",
"check:diagnostics": "node scripts/check-diagnostics.ts",
"check:diagnostics:fixture": "node scripts/check-diagnostics.ts --fixture",
"check:diagnostics": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts",
"check:diagnostics:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts --fixture",
"check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test && corepack pnpm check:types:recipes && corepack pnpm check:types:web-worker && corepack pnpm check:types:service-worker",
"check:types:app": "tsc --project tsconfig.app.json",
"check:types:node": "tsc --project tsconfig.node.json",
"check:types:test": "tsc --project tsconfig.test.json",
"check:types:app": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.app.json",
"check:types:node": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.node.json",
"check:types:test": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.test.json",
"check:types:recipes": "node scripts/check-optional-recipe-types.ts",
"check:types:fixture": "tsc -p tests/fixtures/typecheck/tsconfig.port-call.json",
"check:types:fixture:ts-port": "tsc -p tests/fixtures/typecheck/tsconfig.port-implementation.json",
@@ -39,11 +39,11 @@
"check:types:fixture:failure-kind": "tsc -p tests/fixtures/typecheck/tsconfig.failure-kind.json",
"check:types:fixture:reference-operation": "tsc -p tests/fixtures/typecheck/tsconfig.reference-operation.json",
"check:types:fixture:async-overlay": "tsc -p tests/fixtures/typecheck/tsconfig.async-overlay.json",
"check:types:fixture:route-runtime": "tsc -p tests/fixtures/typecheck/tsconfig.route-runtime.json",
"check:types:fixture:page-action": "tsc -p tests/fixtures/typecheck/tsconfig.page-action.json",
"check:types:fixture:icon-button": "tsc -p tests/fixtures/typecheck/tsconfig.icon-button.json",
"check:types:fixture:i18n-key": "tsc -p tests/fixtures/typecheck/tsconfig.message-key.json",
"check:types:fixture:i18n-params": "tsc -p tests/fixtures/typecheck/tsconfig.message-params.json",
"check:types:fixture:route-runtime": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.route-runtime.json",
"check:types:fixture:page-action": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.page-action.json",
"check:types:fixture:icon-button": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.icon-button.json",
"check:types:fixture:i18n-key": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.message-key.json",
"check:types:fixture:i18n-params": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.message-params.json",
"check:types:fixture:diagnostics": "tsc -p tests/fixtures/typecheck/tsconfig.diagnostics-port.json",
"check:types:fixture:image-resolve-signal": "tsc -p tests/fixtures/typecheck/tsconfig.image-cdn-resolve-signal.json",
"test:runtime-schema": "node scripts/run-vitest.ts run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
@@ -59,8 +59,8 @@
"test:e2e:dev": "playwright test --config playwright.dev.config.ts",
"test:browser-capabilities": "playwright test --config playwright.capabilities.config.ts",
"verify:browser-capability-evidence": "node scripts/verify-browser-capability-evidence.ts",
"storybook": "storybook dev -p 6006",
"build:storybook": "storybook build -o artifacts/storybook/static",
"storybook": "node scripts/generate-product-feature-index.ts && storybook dev -p 6006",
"build:storybook": "node scripts/generate-product-feature-index.ts && storybook build -o artifacts/storybook/static",
"test:storybook": "playwright test --config playwright.storybook.config.ts",
"test:visual": "playwright test --config playwright.visual.config.ts",
"test:visual:update": "playwright test --config playwright.visual.config.ts --update-snapshots",
@@ -70,8 +70,8 @@
"check:http-scenario-evidence:fixture": "node scripts/check-test-evidence.ts --scenario-only --source-root tests/fixtures/test-evidence/scenarios/source --policy tests/fixtures/test-evidence/scenarios/policy.json --catalog tests/fixtures/test-evidence/scenarios/catalog.json --receipt tests/fixtures/test-evidence/scenarios/receipt.json --artifact artifacts/quality/http-scenario-evidence-fixture.json",
"check:test-evidence:source": "node scripts/check-test-evidence.ts --source-only --artifact artifacts/quality/test-evidence-source.json",
"check:test-evidence:fixture": "node scripts/check-test-evidence.ts --source-root tests/fixtures/test-evidence/forbidden --artifact artifacts/quality/test-evidence-fixture.json",
"test:a11y": "playwright test --grep @a11y && node scripts/write-a11y-report.ts",
"review:a11y-manual": "node scripts/verify-a11y-manual.ts",
"test:a11y": "node scripts/generate-product-feature-index.ts && playwright test --grep @a11y && node scripts/write-a11y-report.ts",
"review:a11y-manual": "node scripts/generate-product-feature-index.ts && node scripts/verify-a11y-manual.ts",
"test:sample-removal": "node scripts/test-sample-removal.ts",
"test:optional-recipe-removal": "node scripts/test-optional-recipe-removal.ts",
"test:browser-file-storage-removal": "node scripts/test-browser-file-storage-runtime-removal.ts",
@@ -83,46 +83,46 @@
"test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:contract && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature && corepack pnpm test:platform && corepack pnpm check:release-coherence && corepack pnpm test:recipes",
"verify:lockfile": "corepack pnpm install --frozen-lockfile --ignore-scripts",
"check:frozen-lockfile:fixture": "node scripts/check-frozen-lockfile-fixture.ts",
"generate:artifact-schemas": "node scripts/generate-artifact-schemas.ts",
"check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check",
"generate:supply-chain": "node scripts/generate-supply-chain.ts",
"verify:local-evidence": "node scripts/verify-release-candidate.ts && node scripts/verify-release.ts && node scripts/verify-supply-chain-artifacts.ts && node scripts/verify-archived-local-evidence.ts && node scripts/verify-release-candidate.ts",
"verify:promotion": "node scripts/verify-exact-promotion-bundle.ts",
"generate:artifact-schemas": "node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts",
"check:artifact-schemas": "node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts --check",
"generate:supply-chain": "node scripts/generate-product-feature-index.ts && node scripts/generate-supply-chain.ts",
"verify:local-evidence": "node scripts/generate-product-feature-index.ts && node scripts/verify-release-candidate.ts && node scripts/verify-release.ts && node scripts/verify-supply-chain-artifacts.ts && node scripts/verify-archived-local-evidence.ts && node scripts/verify-release-candidate.ts",
"verify:promotion": "node scripts/generate-product-feature-index.ts && node scripts/verify-exact-promotion-bundle.ts",
"update:dependency-baseline": "node scripts/update-dependency-baseline.ts",
"check:supply-chain:fixtures": "node scripts/check-supply-chain-fixtures.ts",
"check:supply-chain:provider-fixtures": "node scripts/check-supply-chain-provider-fixtures.ts",
"verify:reproducible-build": "node scripts/verify-reproducible-build.ts",
"check:supply-chain:fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-supply-chain-fixtures.ts",
"check:supply-chain:provider-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-supply-chain-provider-fixtures.ts",
"verify:reproducible-build": "node scripts/generate-product-feature-index.ts && node scripts/verify-reproducible-build.ts",
"scan:security": "node scripts/security-scan.ts",
"scan:security:fixture": "node scripts/security-scan.ts --policy tests/fixtures/security/secret-detection/forbidden-policy.json --artifact artifacts/security/scan-fixture.sarif",
"check:security:fixtures": "node scripts/check-security-fixtures.ts",
"check:browser-security": "node scripts/check-browser-security.ts",
"check:browser-file-storage-boundaries": "node scripts/check-browser-file-storage-boundaries.ts",
"check:realtime-boundaries": "node scripts/check-realtime-boundaries.ts",
"check:realtime-boundaries": "node scripts/generate-product-feature-index.ts && node scripts/check-realtime-boundaries.ts",
"check:realtime-boundaries:fixture": "node scripts/check-realtime-boundary-fixtures.ts",
"check:optional-recipes": "node scripts/check-optional-recipes.ts --require-dist",
"check:optional-recipes:source": "node scripts/check-optional-recipes.ts",
"check:optional-recipe-fixtures": "node scripts/check-optional-recipe-fixtures.ts",
"check:registries": "node scripts/check-registries.ts",
"check:registries:structure": "node scripts/check-registries.ts --no-baseline",
"check:registries:compatibility-fixtures": "node scripts/check-registry-compatibility-fixtures.ts",
"check:registries:baseline-fixture": "node scripts/check-registries.ts --approval tests/fixtures/registry/compatibility/tampered-approval.json --artifact artifacts/quality/registry-baseline-fixture.json",
"check:registries:fixture": "node scripts/check-registries.ts --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
"check:routes:fixture": "node scripts/check-registries.ts --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
"verify:compatibility": "node scripts/check-compatibility.ts",
"verify:release": "node scripts/verify-release.ts",
"verify:hosting-headers": "node scripts/verify-hosting-headers.ts",
"check:bundle": "node scripts/generate-supply-chain.ts && node scripts/check-bundle.ts",
"test:performance": "node scripts/test-performance.ts",
"collect:web-vitals-evidence": "node scripts/collect-web-vitals-evidence.ts",
"drill:runbook": "node scripts/drill-runbook.ts",
"check:optional-recipes": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipes.ts --require-dist",
"check:optional-recipes:source": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipes.ts",
"check:optional-recipe-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipe-fixtures.ts",
"check:registries": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts",
"check:registries:structure": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --no-baseline",
"check:registries:compatibility-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-registry-compatibility-fixtures.ts",
"check:registries:baseline-fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --approval tests/fixtures/registry/compatibility/tampered-approval.json --artifact artifacts/quality/registry-baseline-fixture.json",
"check:registries:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
"check:routes:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
"verify:compatibility": "node scripts/generate-product-feature-index.ts && node scripts/check-compatibility.ts",
"verify:release": "node scripts/generate-product-feature-index.ts && node scripts/verify-release.ts",
"verify:hosting-headers": "node scripts/generate-product-feature-index.ts && node scripts/verify-hosting-headers.ts",
"check:bundle": "node scripts/generate-product-feature-index.ts && node scripts/generate-supply-chain.ts && node scripts/check-bundle.ts",
"test:performance": "node scripts/generate-product-feature-index.ts && node scripts/test-performance.ts",
"collect:web-vitals-evidence": "node scripts/generate-product-feature-index.ts && node scripts/collect-web-vitals-evidence.ts",
"drill:runbook": "node scripts/generate-product-feature-index.ts && node scripts/drill-runbook.ts",
"drill:runbooks": "corepack pnpm drill:runbook -- FE-RB-001 && corepack pnpm drill:runbook -- FE-RB-002 && corepack pnpm drill:runbook -- FE-RB-003 && corepack pnpm drill:runbook -- FE-RB-004 && corepack pnpm drill:runbook -- FE-RB-005",
"ci:gate": "node scripts/run-ci-gate.ts",
"ci:gate": "node scripts/generate-product-feature-index.ts && node scripts/run-ci-gate.ts",
"generate:ci-workflow": "node scripts/generate-ci-workflow.ts",
"check:ci-workflow": "node scripts/generate-ci-workflow.ts --check",
"check:ci": "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow",
"verify:documentation": "node scripts/verify-documentation-readiness.ts",
"build:app-only": "vite build && node scripts/generate-build-manifest.ts",
"generate:contract-set": "node scripts/generate-contract-set.ts",
"verify:documentation": "node scripts/generate-product-feature-index.ts && node scripts/verify-documentation-readiness.ts",
"build:app-only": "node scripts/generate-product-feature-index.ts && vite build && node scripts/generate-build-manifest.ts",
"generate:contract-set": "node scripts/generate-product-feature-index.ts && node scripts/generate-contract-set.ts",
"check:types:web-worker": "tsc --project tsconfig.web-worker.json",
"check:types:service-worker": "tsc --project tsconfig.service-worker.json",
"check:types:fixture:http-operation-input": "tsc -p tests/fixtures/typecheck/tsconfig.http-operation-input.json",
+4 -1
View File
@@ -573,7 +573,10 @@ export async function loadCiGateContract(
throw new TypeError("check:ci must use the exact canonical non-recursive orchestration");
}
const canonicalCheckCiDependencies = {
"check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check",
// R-0. The schema generator imports src, which loads the gitignored
// product index, so the index is rendered first.
"check:artifact-schemas":
"node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts --check",
"check:ci-workflow": mode === "canonical"
? "node scripts/generate-ci-workflow.ts --check"
: "node scripts/generate-ci-workflow.ts --check --reduced-removal-fixture",
+2 -1
View File
@@ -10,6 +10,7 @@ import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
import path from "node:path";
import {
HASHED_STATIC_ASSET_NAME,
SERVICE_WORKER_BOUNDS,
SERVICE_WORKER_SCRIPT_PATH,
type StaticAssetManifestV1,
@@ -38,7 +39,7 @@ const EXCLUDED_FILES: ReadonlySet<string> = new Set([
]);
/** Vite emits content-hashed names; only those may be treated as immutable. */
const HASHED_NAME = /-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/;
const HASHED_NAME = HASHED_STATIC_ASSET_NAME;
export async function collectStaticAssets(
distDirectory: string,
+12
View File
@@ -47,6 +47,18 @@ for (const key of [
delete testEnvironment[key];
}
// src/.generated is gitignored; every suite imports the product index, so a
// fresh checkout must render it before Vitest resolves the module graph.
const generated = spawnSync(
process.execPath,
[fileURLToPath(new URL("./generate-product-feature-index.ts", import.meta.url))],
{ stdio: "inherit", env: testEnvironment },
);
if (generated.status !== 0) {
process.stderr.write("Product feature index generation failed.\n");
process.exit(generated.status ?? 1);
}
const result = spawnSync(
process.execPath,
[vitestEntry, ...process.argv.slice(2)],
@@ -9,6 +9,8 @@ import { CREDENTIAL_HEADER_NAMES } from "../../contracts/rest-profiles.ts";
export type ExternalSessionOwner = Readonly<{
readState(): SessionState;
/** Opaque subject identifier; see `SessionGateway.getSubject`. */
readSubject?(): string | null;
subscribe(listener: () => void): () => void;
beginSignIn(returnTo?: string): Promise<void>;
signOut(): Promise<void>;
@@ -35,6 +37,8 @@ export function validateCredentialPatch(value: unknown): CredentialPatch {
for (const [name, headerValue] of Object.entries(headers)) {
const normalizedName = name.toLowerCase();
if (
// Names that differ only in case would silently overwrite each other.
Object.hasOwn(projected, normalizedName) ||
!ALLOWED_CREDENTIAL_HEADERS.has(normalizedName) ||
typeof headerValue !== "string" ||
headerValue.length === 0 ||
@@ -53,6 +57,7 @@ export function createExternalAuthSessionAdapter(
): AuthSessionPort {
return Object.freeze({
getState: () => owner.readState(),
getSubject: () => owner.readSubject?.() ?? null,
subscribe: (listener) => owner.subscribe(listener),
beginSignIn: (returnTo) => owner.beginSignIn(returnTo),
signOut: () => owner.signOut(),
@@ -109,6 +114,9 @@ export function createDemoSessionAdapter(
let state = initialState;
const listeners = new Set<() => void>();
const setState = (next: SessionState) => {
// A notification means "the session changed"; repeating the same value
// would make every subscriber redo its work for nothing.
if (next === state) return;
state = next;
for (const listener of listeners) listener();
};
@@ -431,8 +431,11 @@ export class EnhancedFilePicker implements DisposableFilePicker {
if (typeof options.showOpenFilePicker !== "function") {
throw new TypeError("Enhanced file picker API is invalid.");
}
// Bound to undefined, not to options: `window.showOpenFilePicker` throws
// "Illegal invocation" for any other receiver, and Web IDL maps an
// undefined receiver to the global object.
this.#showOpenFilePicker =
options.showOpenFilePicker.bind(options);
options.showOpenFilePicker.bind(undefined);
this.#captureHandles =
options.vault.captureHandles.bind(options.vault);
this.#releaseFile = options.vault.release.bind(options.vault);
@@ -224,8 +224,11 @@ export function createDownloadDeliveryAdapter(
: {}),
...(originalShowSaveFilePicker
? {
// Bound to undefined, not to options: `window.showSaveFilePicker`
// throws "Illegal invocation" for any other receiver, and Web IDL
// maps an undefined receiver to the global object.
showSaveFilePicker:
originalShowSaveFilePicker.bind(options),
originalShowSaveFilePicker.bind(undefined),
}
: {}),
...(originalIntegrityVerifier
@@ -731,34 +734,34 @@ async function boundedObjectUrlHandoff(context: Readonly<{
);
}
const sourceHolder = createSourceHolder();
const sourceResult = await resolveByteSource(
context.input,
context.input.signal,
context.options,
sourceHolder,
);
if (!sourceResult.ok) {
closeHeldSource(sourceHolder);
return observeResult(sourceResult, context.options.observer);
}
const source = sourceResult.value;
if (
source.byteLength !== null &&
(source.byteLength > context.input.maxBufferedBytes ||
source.byteLength > context.input.maxTransferBytes)
) {
closeHeldSource(sourceHolder);
return observeResult(
browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD"),
context.options.observer,
source.byteLength,
);
}
const chunks: ArrayBuffer[] = [];
let transferred = 0;
let lease: ObjectUrlLease | undefined;
try {
// Inside the try: an open that throws or is aborted must still resolve to
// a Result and reach the finally that latches the holder for late leases.
const sourceResult = await resolveByteSource(
context.input,
context.input.signal,
context.options,
sourceHolder,
);
if (!sourceResult.ok) {
return observeResult(sourceResult, context.options.observer);
}
const source = sourceResult.value;
if (
source.byteLength !== null &&
(source.byteLength > context.input.maxBufferedBytes ||
source.byteLength > context.input.maxTransferBytes)
) {
return observeResult(
browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD"),
context.options.observer,
source.byteLength,
);
}
context.progress.report("PREPARING", 0, source.byteLength, true);
for await (const chunkResult of abortableFileChunks(
source,
@@ -32,10 +32,10 @@ import type {
PresignedCapabilityVault,
PresignedHeaderBinding,
} from "./presigned-capability-vault.ts";
import { SAFE_TRANSFER_ID } from "../resumable-upload/checkpoint-schema.ts";
const SHA256 = /^[a-f0-9]{64}$/;
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/;
const OPAQUE_ID = /^[a-z0-9][a-z0-9._:-]{0,255}$/i;
const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
const QUERY_NAME = /^[A-Za-z0-9_.~-]{1,128}$/;
const FORBIDDEN_REQUEST_HEADERS = new Set([
@@ -1116,8 +1116,8 @@ function normalizedSha256(value: unknown): string {
}
function snapshotOpaqueId(value: unknown, name: string): string {
const id = requiredString(value, 256);
if (!OPAQUE_ID.test(id)) throw new TypeError(`${name} is invalid.`);
const id = requiredString(value, 512);
if (!SAFE_TRANSFER_ID.test(id)) throw new TypeError(`${name} is invalid.`);
return id;
}
@@ -34,6 +34,7 @@ import type {
PresignedCapabilityBinding,
PresignedCapabilityVault,
} from "./presigned-capability-vault.ts";
import { SAFE_TRANSFER_ID } from "../resumable-upload/checkpoint-schema.ts";
const SHA256 = /^[a-f0-9]{64}$/;
const RECEIPT_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~:+/=-]{0,511}$/;
@@ -1211,12 +1212,7 @@ function normalizedSha256(value: unknown): string {
}
function opaqueId(value: unknown): string {
if (
typeof value !== "string" ||
value.length === 0 ||
value.length > 256 ||
!/^[a-z0-9][a-z0-9._:-]*$/i.test(value)
) {
if (typeof value !== "string" || !SAFE_TRANSFER_ID.test(value)) {
throw new TypeError("Opaque identifier is invalid.");
}
return value;
@@ -9,6 +9,13 @@ import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-tr
export const SAFE_UPLOAD_KEY = /^[A-Za-z0-9][A-Za-z0-9._~:-]{7,127}$/u;
export const SAFE_REGISTRY_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
export const SAFE_OPAQUE_ID = /^[A-Za-z0-9_-]{8,512}$/u;
/**
* R-1.2. The one grammar the presigned layer applies to the IDs a capability
* binds (session, resource, idempotency key, capability receipt). A superset
* of SAFE_OPAQUE_ID, so an ID the control plane accepted is never refused
* later in the same transfer.
*/
export const SAFE_TRANSFER_ID = /^[A-Za-z0-9_-][A-Za-z0-9._:-]{0,511}$/u;
export const SHA256_HEX = /^[a-f0-9]{64}$/u;
export const RECEIPT_TOKEN =
/^[A-Za-z0-9][A-Za-z0-9._~:+/=-]{0,511}$/u;
@@ -193,6 +193,7 @@ export function createResumableUploadRuntime<Capability>(
let closed = false;
let lifecycle: "OPEN" | "CLOSING" | "CLOSED" = "OPEN";
let drain: Promise<BrowserDataResult<void>> | null = null;
let quiescent: Promise<"DRAINED"> | null = null;
const cancelLocalUploads = (uploadKey: string): void => {
if (!SAFE_UPLOAD_KEY.test(uploadKey)) return;
for (const controller of localUploads.get(uploadKey) ?? []) {
@@ -215,7 +216,7 @@ export function createResumableUploadRuntime<Capability>(
}
let request: UploadRequestSnapshot;
try {
request = snapshotRequest(input, dependencies.policy);
request = snapshotRequest(input);
} catch {
return browserDataFailure("INVALID_INPUT", "UPLOAD_SESSION");
}
@@ -329,15 +330,7 @@ export function createResumableUploadRuntime<Capability>(
function startDrain(): Promise<BrowserDataResult<void>> {
drain ??= (async () => {
closed = true;
lifecycle = "CLOSING";
releaseCrossContextCancellation?.();
dependencies.crossContextCancellation?.close();
// Abort every admitted operation, then wait for their real settlement.
lifetime.abort();
for (const controllers of localUploads.values()) {
for (const controller of controllers) controller.abort();
}
quiescent ??= beginTeardown();
// TR-RR-06. Bounded. A non-cooperative mutation lock or provider must not
// make teardown unbounded, and an unproved drain is reported as such
// rather than closed over.
@@ -348,20 +341,13 @@ export function createResumableUploadRuntime<Capability>(
dependencies.policy.cleanupDeadlineMs,
);
});
// TR-04. Quiescence means both registries: the bounded wrappers and the
// raw provider work they may have outlived. A settling wrapper can still
// register more physical work, so the drain repeats until both are empty
// or the cleanup deadline expires.
const quiescent = (async () => {
while (activeOperations.size > 0 || physicalTasks.size > 0) {
await Promise.allSettled([...activeOperations, ...physicalTasks]);
}
return "DRAINED" as const;
})();
const drained = await Promise.race([quiescent, expired]);
if (timer !== undefined) clearTimeout(timer);
if (drained === "EXPIRED") {
// The store stays open: something can still write a checkpoint.
// R-1.1. The failure is retryable, so a later dispose() starts a new
// bounded wait on the same quiescence instead of replaying this one.
drain = null;
return browserDataFailure("UNAVAILABLE", "UPLOAD_ABORT", {
retryable: true,
recovery: "RESUME",
@@ -374,6 +360,28 @@ export function createResumableUploadRuntime<Capability>(
})();
return drain;
}
/** One-shot admission close; returns the quiescence every drain waits on. */
function beginTeardown(): Promise<"DRAINED"> {
closed = true;
lifecycle = "CLOSING";
releaseCrossContextCancellation?.();
dependencies.crossContextCancellation?.close();
// Abort every admitted operation, then wait for their real settlement.
lifetime.abort();
for (const controllers of localUploads.values()) {
for (const controller of controllers) controller.abort();
}
// TR-04. Quiescence means both registries: the bounded wrappers and the
// raw provider work they may have outlived. A settling wrapper can still
// register more physical work, so the drain repeats until both are empty.
return (async () => {
while (activeOperations.size > 0 || physicalTasks.size > 0) {
await Promise.allSettled([...activeOperations, ...physicalTasks]);
}
return "DRAINED" as const;
})();
}
return runtime;
}
@@ -803,18 +811,11 @@ async function transferMissingParts<Capability>(
);
let nextIndex = 0;
let firstFailure: BrowserDataResult<never> | null = null;
const maxByMemory = Math.max(
1,
Math.floor(
dependencies.policy.maxInFlightBytes /
(dependencies.policy.partSizeBytes *
dependencies.policy.partBufferCopyFactor),
),
);
// R-1.3. The resolved policy already fits maxConcurrency parts in
// maxInFlightBytes, so the concurrency createSession requested is real.
const workerCount = Math.min(
dependencies.policy.maxConcurrency,
checkpoint.sessionMaxConcurrency,
maxByMemory,
missing.length,
);
const workers = Array.from({ length: workerCount }, async () => {
@@ -1734,7 +1735,6 @@ function quarantinedOutcome(
function snapshotRequest(
input: ResumableUploadRequest,
policy: ResumableUploadRuntimePolicy,
): UploadRequestSnapshot {
if (
!input ||
@@ -1751,14 +1751,8 @@ function snapshotRequest(
) {
throw new TypeError("Upload request is invalid.");
}
// R-1.4. Size limits are checked by executeUpload as LIMIT_EXCEEDED.
const source = snapshotUploadSource(input.source);
if (
source.byteLength > policy.maxFileBytes ||
Math.ceil(source.byteLength / policy.partSizeBytes) >
policy.maxPartCount
) {
throw new TypeError("Upload request exceeds policy.");
}
return Object.freeze({
uploadKey: input.uploadKey,
purpose: input.purpose,
@@ -44,7 +44,9 @@ const DEFAULT_POLICY: ResumableUploadRuntimePolicy = Object.freeze({
partSizeBytes: 5 * MIB,
maxFileBytes: 5 * GIB,
maxPartCount: 1_024,
maxConcurrency: 3,
// R-1.3. 5 MiB × 1 × copyFactor 4 fills the 20 MiB budget; raise both
// together to upload parts in parallel.
maxConcurrency: 1,
maxInFlightBytes: 20 * MIB,
partBufferCopyFactor: 4,
maxSourceChunkBytes: 8 * MIB,
@@ -80,7 +82,9 @@ export function resolveResumableUploadRuntimePolicy(
policy.partBufferCopyFactor >
ABSOLUTE_LIMITS.maxPartBufferCopyFactor ||
policy.maxInFlightBytes <
policy.partSizeBytes * policy.partBufferCopyFactor ||
policy.partSizeBytes *
policy.maxConcurrency *
policy.partBufferCopyFactor ||
!positiveSafeInteger(policy.maxSourceChunkBytes) ||
policy.maxSourceChunkBytes >
ABSOLUTE_LIMITS.maxSourceChunkBytes ||
@@ -137,6 +137,9 @@ export function assertPublicCachePolicy(
// rejected at composition instead of producing an unusable candidate.
(policy.allowedVaryHeaderNames.length > 0 &&
!policy.allowedResponseHeaderNames.includes("vary")) ||
// Activation re-validates the stored Content-Type, so stripping it would
// make every activation fail as INTEGRITY_FAILED.
!policy.allowedResponseHeaderNames.includes("content-type") ||
policy.forbiddenQueryParameterNames.some((name) => name.length === 0) ||
policy.allowedQueryParameterNames.some((name) =>
policy.forbiddenQueryParameterNames.includes(name),
@@ -1314,6 +1314,11 @@ function validateVary(
const allowed = new Set(policy.allowedVaryHeaderNames);
for (const item of vary.split(",")) {
const name = item.trim().toLowerCase();
// Browser-managed: Accept-Encoding is a forbidden request header, so no
// script-built Request carries it. Stored and lookup requests both lack it
// and Cache.match still matches exactly. nginx `gzip_vary` and most CDNs
// send it on every compressible asset.
if (name === "accept-encoding") continue;
if (
name === "*" ||
name === "authorization" ||
@@ -13,6 +13,12 @@ import {
export type CrossContextInvalidationStatus =
| "ACTIVE_BROADCAST"
| "ACTIVE_STORAGE_FALLBACK"
/**
* The browser has BroadcastChannel but this tab could not open it. Other
* tabs publish on BroadcastChannel only, so this tab misses their events
* while its own storage pulses still reach them.
*/
| "DEGRADED_STORAGE_FALLBACK"
| "DEGRADED_LOCAL_ONLY"
| "CLOSED";
@@ -145,10 +151,9 @@ export type BrowserCrossContextInvalidation = Readonly<{
}>;
type SeenEvent = Readonly<{ expiresAt: number }>;
type SourceHighWatermark = Readonly<{
sequence: number;
expiresAt: number;
}>;
// No TTL: a watermark must outlive its last event, or the next event after a
// quiet period reads as a GAP. `sourceCapacity` LRU bounds the memory.
type SourceHighWatermark = Readonly<{ sequence: number }>;
const DEFAULT_EVENT_TTL_MS = 60_000;
const DEFAULT_DEDUPE_CAPACITY = 1_024;
@@ -177,6 +182,10 @@ export function createBrowserCrossContextInvalidation(
let closed = false;
let sequence = 0;
let broadcast: BroadcastChannelFacade | undefined;
let broadcastOpenFailed = false;
// A failed postMessage moves publishing to storage but keeps the channel
// open, because other tabs keep publishing on it.
let broadcastPublishFailed = false;
let storageListenerInstalled = false;
let status: CrossContextInvalidationStatus = "DEGRADED_LOCAL_ONLY";
@@ -250,6 +259,7 @@ export function createBrowserCrossContextInvalidation(
// Opening still falls back when provider cleanup is rejected.
}
}
broadcastOpenFailed = true;
observe({
operation: "OPEN",
outcome: "DEGRADED",
@@ -262,14 +272,16 @@ export function createBrowserCrossContextInvalidation(
function refreshStatus(): void {
if (closed) {
status = "CLOSED";
} else if (broadcast) {
} else if (broadcast && !broadcastPublishFailed) {
status = "ACTIVE_BROADCAST";
} else if (
dependencies.storage &&
dependencies.storageEvents &&
storageListenerInstalled
) {
status = "ACTIVE_STORAGE_FALLBACK";
status = broadcastOpenFailed
? "DEGRADED_STORAGE_FALLBACK"
: "ACTIVE_STORAGE_FALLBACK";
} else {
status = "DEGRADED_LOCAL_ONLY";
}
@@ -323,7 +335,7 @@ export function createBrowserCrossContextInvalidation(
sequence = candidate.sequence;
pruneTracking(emittedAt);
if (broadcast) {
if (broadcast && !broadcastPublishFailed) {
try {
broadcast.postMessage(candidate);
observe({
@@ -343,7 +355,7 @@ export function createBrowserCrossContextInvalidation(
transport: "BROADCAST",
reason: "BROADCAST_PUBLISH_FAILED",
});
closeBroadcast();
broadcastPublishFailed = true;
refreshStatus();
}
}
@@ -414,7 +426,7 @@ export function createBrowserCrossContextInvalidation(
reason: "STORAGE_CLEANUP_FAILED",
});
}
status = "ACTIVE_STORAGE_FALLBACK";
refreshStatus();
observe({
operation: "PUBLISH",
outcome: "ACCEPTED",
@@ -497,10 +509,7 @@ export function createBrowserCrossContextInvalidation(
event.sequence > previous.sequence + 1)
? "GAP"
: "NEXT";
touchSource(sourceKey, {
sequence: event.sequence,
expiresAt: event.expiresAt,
});
touchSource(sourceKey, { sequence: event.sequence });
const delivery = Object.freeze({ event, ordering, transport });
for (const listener of [...listeners]) {
@@ -546,11 +555,6 @@ export function createBrowserCrossContextInvalidation(
for (const [eventId, entry] of seenEvents) {
if (entry.expiresAt <= currentTime) seenEvents.delete(eventId);
}
for (const [sourceKey, entry] of sourceHighWatermarks) {
if (entry.expiresAt <= currentTime) {
sourceHighWatermarks.delete(sourceKey);
}
}
}
function subscribe(
+48 -4
View File
@@ -295,9 +295,26 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
): Result<Value, ApiFailure> {
// A throwing feature mapper is a mapping defect, not a transport failure: it
// must not reject and lose the effect the server already confirmed.
const mapperThrew = (
effect: FailureEffectCertainty,
httpStatus: number,
): Result<Value, ApiFailure> =>
failure(
"MAPPING_CONTRACT_VIOLATION",
operationId,
"MAPPING_CONTRACT_VIOLATION",
{ httpStatus, effect },
);
switch (outcome.kind) {
case "SUCCESS": {
const mapped = mapSuccess(outcome.value);
let mapped: MappingResult<Value>;
try {
mapped = mapSuccess(outcome.value);
} catch {
return mapperThrew(outcome.effect, outcome.metadata.status);
}
return mapped.ok
? Object.freeze({ ok: true as const, value: mapped.value })
: failure(
@@ -308,7 +325,12 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
);
}
case "PROBLEM": {
const mapped = mapProblem?.(outcome.problem, outcome.metadata);
let mapped: FeatureHttpProblemMapping | undefined;
try {
mapped = mapProblem?.(outcome.problem, outcome.metadata);
} catch {
return mapperThrew(outcome.effect, outcome.metadata.status);
}
return failure(
mapped?.kind ?? kindForStatus(outcome.metadata.status),
operationId,
@@ -353,16 +375,33 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
outcome.failure.kind,
{ effect: outcome.effect },
);
case "CONTRACT_VIOLATION":
case "CONTRACT_VIOLATION": {
const httpStatus = outcome.metadata?.status;
// R-3.3. A gateway 5xx/408/425 with an HTML or empty body is a server
// outage: keep its status and retryability instead of "contact support".
if (httpStatus !== undefined && isServerFailureStatus(httpStatus)) {
return failure("SERVER_FAILURE", operationId, outcome.violation.kind, {
httpStatus,
effect: outcome.effect,
});
}
return failure(
failureKindForViolation(outcome.violation.kind),
operationId,
outcome.violation.kind,
{ effect: outcome.effect },
{
...(httpStatus === undefined ? {} : { httpStatus }),
effect: outcome.effect,
},
);
}
}
}
function isServerFailureStatus(status: number): boolean {
return status >= 500 || status === 408 || status === 425;
}
function failureKindForViolation(
violation: Extract<
HttpExecutionOutcome<unknown, unknown>,
@@ -385,6 +424,11 @@ function failureKindForViolation(
case "PROBLEM_SCHEMA_INVALID":
case "VALIDATOR_RUNTIME_FAILURE":
return "SCHEMA_MISMATCH";
// Rejected before dispatch: the request, not the server answer, was wrong.
case "FINAL_REQUEST_INVARIANT_FAILED":
case "MISSING_IDEMPOTENCY_KEY":
case "UNEXPECTED_IDEMPOTENCY_KEY":
return "VALIDATION_REJECTED";
default:
return "ENVELOPE_MISMATCH";
}
+25 -4
View File
@@ -50,6 +50,13 @@ export type CredentialAdmissionOutcome =
const MAX_CREDENTIAL_HEADER_VALUE_BYTES = 8_192;
/**
* R-3.4. The one credential value rule for V2 and V3: a ByteString (every code
* unit one byte on the wire) with no C0/C1 control characters. Fetch rejects
* anything else only after the request counts as dispatched.
*/
const CREDENTIAL_HEADER_VALUE = /^[\x20-\x7E\xA0-\xFF]+$/;
/**
* §7.7. Admits a credential patch against the resolved profile before any
* header object is built. A rejection here guarantees `fetch()` is not called:
@@ -82,9 +89,8 @@ export function admitCredentialHeaders(
}
if (
typeof value !== "string" ||
value.length === 0 ||
/[\r\n]/.test(value) ||
encoder.encode(value).byteLength > MAX_CREDENTIAL_HEADER_VALUE_BYTES
!CREDENTIAL_HEADER_VALUE.test(value) ||
value.length > MAX_CREDENTIAL_HEADER_VALUE_BYTES
) {
return frozenAdmissionFailure("CREDENTIAL_HEADER_VALUE_INVALID");
}
@@ -189,7 +195,14 @@ function projectRequestChecked<Input, WireOutput, Problem>(
missing = true;
return "";
}
if (value.includes("/") || value.includes("\\")) {
// A dot segment survives encodeURIComponent and URL resolution would
// move the request to a parent path that still passes the base check.
if (
value.includes("/") ||
value.includes("\\") ||
value === "." ||
value === ".."
) {
invalid = true;
return "";
}
@@ -318,6 +331,7 @@ export type FinalInvariantFailure =
| "CREDENTIAL_HEADER_NOT_ALLOWED"
| "MISSING_REQUIRED_CREDENTIAL_HEADER"
| "FORBIDDEN_HEADER"
| "HEADER_VALUE_INVALID"
| "REQUEST_BODY_TOO_LARGE"
| "DEADLINE_EXPIRED"
| "SCOPE_FENCED";
@@ -376,6 +390,13 @@ export function checkFinalInvariants(
return "MISSING_REQUIRED_CREDENTIAL_HEADER";
}
}
// Fetch validates header values only once it is called; build them here so
// any value it would reject fails before dispatch, not as a network error.
try {
new Headers(input.headers);
} catch {
return "HEADER_VALUE_INVALID";
}
if (
input.request.bodyBytes &&
+21 -3
View File
@@ -134,6 +134,11 @@ export type HttpExecutionOutcome<Value, Problem> =
}>
| Readonly<{
kind: "UNAUTHENTICATED";
/**
* Present only when the server answered 401. Absent means no credential
* existed and nothing was sent; that is not a session verdict.
*/
metadata?: SafeResponseMetadata;
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
}>
| Readonly<{
@@ -148,6 +153,11 @@ export type HttpExecutionOutcome<Value, Problem> =
| Readonly<{
kind: "CONTRACT_VIOLATION";
violation: HttpContractViolation;
/**
* Present when an error status arrived without a usable problem body.
* A 5xx/408/425 here is a server outage, not a contract breach (R-3.3).
*/
metadata?: SafeResponseMetadata;
effect: HttpEffectCertainty;
}>
| Readonly<{
@@ -300,9 +310,7 @@ function observationErrorKind(
function observationStatus(
outcome: HttpExecutionOutcome<unknown, unknown>,
): number | undefined {
return outcome.kind === "SUCCESS" || outcome.kind === "PROBLEM"
? outcome.metadata.status
: undefined;
return "metadata" in outcome ? outcome.metadata?.status : undefined;
}
export type ContractHttpExecutorDependencies = Readonly<{
@@ -1158,6 +1166,7 @@ async function admitResponse<Input, WireOutput, Problem>(
unauthenticated(
certaintyForAbandonedAttempt(attemptState, isCommand),
isCommand,
metadata,
),
"UNAUTHENTICATED",
);
@@ -1490,6 +1499,7 @@ async function admitProblem<Input, WireOutput, Problem>(
"PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1502,6 +1512,7 @@ async function admitProblem<Input, WireOutput, Problem>(
"CONTENT_TYPE_MISMATCH",
"RESPONSE",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1516,6 +1527,7 @@ async function admitProblem<Input, WireOutput, Problem>(
decoded.code,
"RESPONSE",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1534,6 +1546,7 @@ async function admitProblem<Input, WireOutput, Problem>(
"PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: false,
@@ -1550,6 +1563,7 @@ async function admitProblem<Input, WireOutput, Problem>(
: "PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1612,10 +1626,12 @@ function violation<Value, Problem>(
kind: HttpContractViolationKind,
operation: HttpContractViolation["operation"],
effect: HttpEffectCertainty,
metadata?: SafeResponseMetadata,
): HttpExecutionOutcome<Value, Problem> {
return Object.freeze({
kind: "CONTRACT_VIOLATION" as const,
violation: Object.freeze({ kind, operation }),
...(metadata === undefined ? {} : { metadata }),
effect,
});
}
@@ -1652,9 +1668,11 @@ function postDispatchEffect(isCommand: boolean): HttpEffectCertainty {
function unauthenticated<Value, Problem>(
effect: string,
isCommand: boolean,
metadata?: SafeResponseMetadata,
): HttpExecutionOutcome<Value, Problem> {
return Object.freeze({
kind: "UNAUTHENTICATED" as const,
...(metadata === undefined ? {} : { metadata }),
effect: normalizeOptionalEffect(effect, isCommand),
});
}
+3
View File
@@ -73,6 +73,9 @@ export function buildRequestTarget(
if (
serialized.length === 0 ||
serialized.length > 512 ||
// Dot segments are not encoded and pathname assignment normalizes them.
serialized === "." ||
serialized === ".." ||
[...serialized].some((character) => {
const code = character.codePointAt(0) ?? 0;
return code < 32 || code === 127;
@@ -24,7 +24,12 @@ export type ScopeResetParticipant = Readonly<{
}>;
export type ServerStateScopeDependencies = Readonly<{
session: Pick<AuthSessionPort, "subscribe">;
/**
* `getState`/`getSubject` let the runtime skip a notification that changes
* neither. Without `getState` every notification fences, as before.
*/
session: Pick<AuthSessionPort, "subscribe"> &
Partial<Pick<AuthSessionPort, "getState" | "getSubject">>;
queryInvalidation: Pick<QueryInvalidationCoordinator, "resetLocal">;
tokenFactory?: () => string;
participants?: readonly ScopeResetParticipant[];
@@ -49,6 +54,7 @@ export function createServerStateScopeRuntime(
let phase: ClientScopePhase = "READY";
let disposed = false;
let resetChain = Promise.resolve();
let sessionIdentity = readSessionIdentity(dependencies.session);
function createSnapshot(): CacheScopeSnapshot {
const capturedGeneration = generation;
@@ -89,6 +95,18 @@ export function createServerStateScopeRuntime(
const unsubscribe = dependencies.session.subscribe(() => {
if (disposed) return;
// §10.6 is for identity-affecting changes only. A notification that keeps
// (state, subject) — a token refresh, a repeated sign-out — must not abort
// requests and clear the cache. A FAILED scope still retries its reset.
const nextSessionIdentity = readSessionIdentity(dependencies.session);
if (
nextSessionIdentity !== null &&
nextSessionIdentity === sessionIdentity &&
phase !== "FAILED"
) {
return;
}
sessionIdentity = nextSessionIdentity;
const previousIdentities = identities;
const previousGeneration = generation;
@@ -185,6 +203,26 @@ export function createServerStateScopeRuntime(
});
}
/**
* `null` means the identity cannot be proven unchanged: no `getState`, a
* throwing owner, or an authenticated session without a subject. Those always
* fence, which keeps an account switch from reusing the previous cache.
*/
function readSessionIdentity(
session: ServerStateScopeDependencies["session"],
): string | null {
try {
const state = session.getState?.();
if (state === undefined) return null;
const subject = session.getSubject?.();
const knownSubject = typeof subject === "string" ? subject : null;
if (state === "authenticated" && knownSubject === null) return null;
return JSON.stringify([state, knownSubject]);
} catch {
return null;
}
}
function newIdentityRegistry(
tokenFactory: (() => string) | undefined,
): RuntimeIdentityRegistry {
+8
View File
@@ -178,6 +178,14 @@ function projectTransportOutcome(
streamId: StreamRegistrationId | null,
): RealtimeResult<RealtimeTransportEventOutcome> {
if (!accepted.ok) return accepted;
// A recovery with no barrier to confirm keeps the connection; handing it to
// the reconnect path would ask for a barrier the coordinator never set.
if (
accepted.value.outcome === "RECOVERED" &&
accepted.value.transportBarrierRequired === false
) {
return realtimeSuccess(REALTIME_TRANSPORT_CONTINUE);
}
if (
accepted.value.outcome === "RECOVERED" ||
accepted.value.outcome === "RECOVERY_BARRIER_REQUIRED"
@@ -341,11 +341,11 @@ export function createBoundedPollCoordinator<Value>(
}
result = parsedResult;
if (!result.ok) {
// A missing server hint falls back to policy backoff; an executor
// that requires one reports `retryable: false` instead.
if (
!result.error.retryable ||
!isPollRetryableFailureKind(result.error.kind) ||
(isPollRetryAfterFailureKind(result.error.kind) &&
result.error.retryAfterMs === undefined)
!isPollRetryableFailureKind(result.error.kind)
) {
return pollFailure(result.error.kind);
}
+7 -23
View File
@@ -717,12 +717,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
settleAttemptGate(opened.failure.result);
phase.controller.abort();
phase.dispose();
if (
!reconnectable(
opened.failure,
opened.serverNotBeforeMs,
)
) {
if (!reconnectable(opened.failure)) {
return opened.failure.result;
}
const failedAt = safeNow(clock);
@@ -934,12 +929,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
if (classified.outcome.ok) {
return classified.outcome.result as RealtimeResult<void>;
}
if (
!reconnectable(
classified.outcome.failure,
classified.outcome.serverNotBeforeMs,
)
) {
if (!reconnectable(classified.outcome.failure)) {
return classified.outcome.failure.result;
}
@@ -1658,17 +1648,11 @@ function providerRetry(
);
}
function reconnectable(
failureSnapshot: FailureSnapshot,
serverNotBeforeMs: number | null,
): boolean {
if (
serverNotBeforeMs === null &&
(failureSnapshot.kind === "RATE_LIMITED" ||
failureSnapshot.kind === "PROVIDER_UNAVAILABLE")
) {
return false;
}
/**
* A transport that needs a server hint and did not get one already reports
* `retryable: false`, so a missing hint alone never ends the loop.
*/
function reconnectable(failureSnapshot: FailureSnapshot): boolean {
return (
failureSnapshot.retryable &&
RETRYABLE_KINDS.includes(
+41 -27
View File
@@ -13,6 +13,8 @@ export const SSE_PARSER_CEILINGS = Object.freeze({
maxRetryMs: 60_000,
});
const LINE_BREAK = /[\r\n]/gu;
export type SseParserLimits = Readonly<{
maxLineBytes: number;
maxEventBytes: number;
@@ -130,49 +132,61 @@ export function createIncrementalSseParser(
);
}
/**
* Works a line at a time: find the next CR/LF, append the text before it
* and count its UTF-8 bytes once. Byte counts only grow within a line, so
* checking the limits per segment fails exactly where a per-character check
* would.
*/
function consumeText(
text: string,
): RealtimeResult<readonly SseParserItem[]> {
const items: SseParserItem[] = [];
for (const character of text) {
if (atStart) {
atStart = false;
if (character === "\uFEFF") continue;
}
let index = 0;
if (atStart && text.length > 0) {
atStart = false;
if (text.charCodeAt(0) === 0xfeff) index = 1;
}
while (index < text.length) {
if (pendingCarriageReturn) {
pendingCarriageReturn = false;
const processed = processLine(character === "\n" ? 2 : 1);
const lineFeed = text.charCodeAt(index) === 0x0a;
const processed = processLine(lineFeed ? 2 : 1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
if (character === "\n") continue;
if (lineFeed) {
index += 1;
continue;
}
}
if (character === "\r") {
LINE_BREAK.lastIndex = index;
const lineBreak = LINE_BREAK.exec(text)?.index ?? text.length;
if (lineBreak > index) {
const segment = text.slice(index, lineBreak);
line += segment;
lineBytes += encoder.encode(segment).byteLength;
if (
lineBytes > resolved.maxLineBytes ||
lineBytes + blockBytes > resolved.maxIncompleteBufferBytes
) {
return fail("EVENT_TOO_LARGE");
}
}
if (lineBreak === text.length) break;
index = lineBreak + 1;
if (text.charCodeAt(lineBreak) === 0x0d) {
pendingCarriageReturn = true;
continue;
}
if (character === "\n") {
const processed = processLine(1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
continue;
}
line += character;
lineBytes += encoder.encode(character).byteLength;
if (lineBytes > resolved.maxLineBytes) {
return fail("EVENT_TOO_LARGE");
}
if (
lineBytes + blockBytes >
resolved.maxIncompleteBufferBytes
) {
return fail("EVENT_TOO_LARGE");
const processed = processLine(1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
}
return success(Object.freeze(items));
+9 -1
View File
@@ -707,7 +707,9 @@ export function createRealtimeStreamCoordinator(
if (!calledFromCurrentJob) {
await quiescence;
}
if (closed || state.closed) {
// RT-RR-01. The effect this recovery waited on can time out and keep
// running; recovering beside it would let its late write win.
if (closed || state.closed || state.lifecycle === "DRAINING") {
state.freshness = "UNKNOWN";
return realtimeFailure("CLOSED", "RECOVER");
}
@@ -907,6 +909,9 @@ export function createRealtimeStreamCoordinator(
outcome: "RECOVERED" as const,
reason,
resumeState: result.value,
transportBarrierRequired: recoveryRequiresTransportBarrier(
state.registration,
),
}),
);
}
@@ -950,6 +955,9 @@ export function createRealtimeStreamCoordinator(
outcome: "RECOVERED" as const,
reason,
resumeState: result.value,
transportBarrierRequired: recoveryRequiresTransportBarrier(
state.registration,
),
}),
);
}
@@ -89,18 +89,32 @@ self.addEventListener("activate", (event) => {
event.waitUntil(runtime.onActivate());
});
self.addEventListener("fetch", (event) => {
const request = event.request;
event.respondWith(
runtime
.onFetch({
method: request.method,
url: request.url,
mode: request.mode,
})
.then((cached) => cached ?? fetch(request)),
);
});
// R-6.6. Without the static asset handler there is nothing to answer, and
// no fetch listener means the browser never boots this worker for a fetch.
if (handlers.includes("PWA_STATIC_ASSETS")) {
self.addEventListener("fetch", (event) => {
const request = event.request;
// R-6.6. Decided synchronously: only a GET for a verified static asset of
// this release is answered. Navigations, API calls and cross-origin
// requests are left to the browser untouched.
if (
request.method !== "GET" ||
request.mode === "navigate" ||
!runtime.manifestUrls.has(request.url)
) {
return;
}
event.respondWith(
runtime
.onFetch({
method: request.method,
url: request.url,
mode: request.mode,
})
.then((cached) => cached ?? fetch(request)),
);
});
}
self.addEventListener("message", (event) => {
const parsed = parseServiceWorkerMessage(event.data);
@@ -1,4 +1,5 @@
import {
HASHED_STATIC_ASSET_NAME,
SERVICE_WORKER_BOUNDS,
isOwnedStaticCacheName,
staticCacheName,
@@ -119,7 +120,6 @@ export function createServiceWorkerRuntime(
);
const consumedNonces = new Set<string>();
type PendingActivation = Readonly<{
requesterBuildId: string;
expectedClientIds: ReadonlySet<string>;
acknowledgedClientIds: Set<string>;
resolve(drained: boolean): void;
@@ -154,19 +154,8 @@ export function createServiceWorkerRuntime(
const owned = names.filter(isOwnedStaticCacheName);
const currentCache = await scope.caches.open(current);
const oldCaches = owned.filter((name) => name !== current);
const markers: ActivationMarker[] = [];
for (const name of oldCaches) {
const marker = await readActivationMarker(await scope.caches.open(name), name);
if (marker) markers.push(marker);
}
const highestOld = await highestMarkedCache(names, current);
const currentMarker = await readActivationMarker(currentCache, current);
const highestOld = markers.reduce<ActivationMarker | null>(
(highest, marker) =>
!highest || marker.activationSequence >= highest.activationSequence
? marker
: highest,
null,
);
const previous = highestOld?.cacheName ?? oldCaches.at(-1) ?? null;
if (
!currentMarker ||
@@ -200,6 +189,55 @@ export function createServiceWorkerRuntime(
return deleted;
}
/** The owned non-current cache with the highest activation marker. */
async function highestMarkedCache(
names: readonly string[],
current: string,
): Promise<ActivationMarker | null> {
let highest: ActivationMarker | null = null;
for (const name of names) {
if (!isOwnedStaticCacheName(name) || name === current) continue;
const marker = await readActivationMarker(
await scope.caches.open(name),
name,
);
if (
marker &&
(!highest || marker.activationSequence >= highest.activationSequence)
) {
highest = marker;
}
}
return highest;
}
/**
* R-6.3 / D-7. A hashed URL names immutable bytes, so the copy kept in the
* previous release cache (found by its activation marker) is the same
* response. Any other URL is never answered from a previous release.
*/
async function matchPreviousRelease(
url: string,
current: string,
): Promise<Response | null> {
try {
if (!HASHED_STATIC_ASSET_NAME.test(new URL(url).pathname)) return null;
const previous = await highestMarkedCache(
await scope.caches.keys(),
current,
);
if (!previous) return null;
const cached = await (
await scope.caches.open(previous.cacheName)
).match(url);
return cached?.status === 200 && cached.type !== "opaque"
? cached
: null;
} catch {
return null;
}
}
/**
* §18.5–§18.7. A verified cache hit is returned; anything else goes to the
* network and is never written back into the active cache at runtime.
@@ -236,7 +274,7 @@ export function createServiceWorkerRuntime(
} catch {
return null;
}
if (!cached) return null;
if (!cached) return matchPreviousRelease(request.url, currentCacheName);
if (cached.status !== 200 || cached.type === "opaque") {
// §18.6. An invalid hit is deleted from the cache it was read from and
// treated as a release mismatch.
@@ -276,13 +314,9 @@ export function createServiceWorkerRuntime(
const clients = candidates.filter((client) =>
isClientWithinRegistrationScope(client.url, scope.registrationScope),
);
const drained = await drainClients(
clients,
nonce,
parsed.message.sourceBuildId,
);
const drained = await drainClients(clients, nonce);
if (!drained) {
notifyClients(clients, "ACTIVATE_REJECTED", parsed.message.sourceBuildId, nonce);
notifyClients(clients, "ACTIVATE_REJECTED", nonce);
return "REJECTED";
}
@@ -292,28 +326,25 @@ export function createServiceWorkerRuntime(
try {
await scope.skipWaiting();
} catch {
notifyClients(clients, "ACTIVATE_REJECTED", parsed.message.sourceBuildId, nonce);
notifyClients(clients, "ACTIVATE_REJECTED", nonce);
return "REJECTED";
}
// Post-commit notifications are per-client best effort.
notifyClients(clients, "ACTIVATE_ACCEPTED", parsed.message.sourceBuildId, nonce);
notifyClients(
clients,
"ACTIVATED_RELOAD_REQUIRED",
parsed.message.sourceBuildId,
nonce,
);
notifyClients(clients, "ACTIVATE_ACCEPTED", nonce);
notifyClients(clients, "ACTIVATED_RELOAD_REQUIRED", nonce);
return "ACCEPTED";
}
/**
* SW-08. One client's `postMessage()` throwing must not break the whole
* activation event; delivery is isolated per client.
*
* R-6.3. Untargeted: every tab, whatever build it runs, has to see
* ACTIVATED_RELOAD_REQUIRED. The requester pairs its reply by nonce.
*/
function notifyClients(
clients: readonly WorkerClientLike[],
kind: "ACTIVATE_REJECTED" | "ACTIVATE_ACCEPTED" | "ACTIVATED_RELOAD_REQUIRED",
targetBuildId: string,
nonce: string,
): void {
for (const client of clients) {
@@ -322,7 +353,6 @@ export function createServiceWorkerRuntime(
createServiceWorkerMessage({
kind,
sourceBuildId: config.identity.buildId,
targetBuildId,
nonce,
}),
);
@@ -335,7 +365,6 @@ export function createServiceWorkerRuntime(
async function drainClients(
clients: readonly WorkerClientLike[],
nonce: string,
requesterBuildId: string,
): Promise<boolean> {
// SW-07. No in-scope client means nothing dirty to drain, so the set is
// vacuously drained. A `clients.matchAll()` failure still rejects upstream.
@@ -348,7 +377,6 @@ export function createServiceWorkerRuntime(
pendingActivations.set(
nonce,
Object.freeze({
requesterBuildId,
expectedClientIds: new Set(clients.map((client) => client.id)),
acknowledgedClientIds: new Set<string>(),
resolve,
@@ -359,13 +387,15 @@ export function createServiceWorkerRuntime(
// SW-08. A client that cannot receive the drain request can never
// acknowledge it, so it fails immediately instead of holding the pending
// state until the timeout.
// R-6.2. Clients run whatever build they loaded, which is usually not the
// requester's. The request is untargeted; replies are paired by this
// worker's buildId, the nonce and the exact client id.
for (const client of clients) {
try {
client.postMessage(
createServiceWorkerMessage({
kind: "CLIENT_DRAIN_REQUEST",
sourceBuildId: config.identity.buildId,
targetBuildId: requesterBuildId,
nonce,
}),
);
@@ -389,11 +419,7 @@ export function createServiceWorkerRuntime(
return;
}
const pending = pendingActivations.get(parsed.message.nonce);
if (
!pending ||
parsed.message.sourceBuildId !== pending.requesterBuildId ||
!pending.expectedClientIds.has(sourceClientId)
) {
if (!pending || !pending.expectedClientIds.has(sourceClientId)) {
return;
}
if (parsed.message.kind === "ACTIVATE_REJECTED") {
@@ -63,6 +63,9 @@ export function createServiceWorkerPageController(
let resetInFlight: Promise<ServiceWorkerResetOutcome> | null = null;
let stopped = false;
const pendingStops = new Set<() => void>();
let updateFoundListener: (() => void) | null = null;
const reloadRequiredListeners = new Set<() => void>();
const updateWaitingListeners = new Set<() => void>();
const observe = (event: string, outcome: string) =>
dependencies.observe?.({ event, outcome });
@@ -178,12 +181,26 @@ export function createServiceWorkerPageController(
}
attachMessageListener(container);
watchForUpdates(registration);
scheduleUpdateChecks();
if (registration.waiting) {
observe("register", "UPDATE_WAITING");
return Object.freeze({ kind: "UPDATE_WAITING" as const });
}
// R-6.4. On a first visit `register()` resolves while the only worker is
// still installing, and that install can fail. Nothing is ACTIVE until it
// settles.
if (!registration.active) {
const settled = registration.installing
? await installSettled(registration.installing)
: "INSTALL_FAILED";
if (stopped) return failed("STOPPED");
if (settled !== "ACTIVATED" || !registration.active) {
observe("register", settled);
return failed(settled);
}
}
// §17.13. Without `clients.claim()` the first install leaves this page
// uncontrolled. That is reported, never silently reloaded.
if (registration.active && !container.controller) {
@@ -197,6 +214,38 @@ export function createServiceWorkerPageController(
});
}
/**
* R-6.4. Waits for a first-install worker to become `activated` or
* `redundant`, bounded by the worker's own install deadline and by stop().
*/
function installSettled(
worker: ServiceWorker,
): Promise<"ACTIVATED" | "INSTALL_FAILED" | "INSTALL_TIMEOUT" | "STOPPED"> {
return new Promise((resolve) => {
const finish = (
outcome: "ACTIVATED" | "INSTALL_FAILED" | "INSTALL_TIMEOUT" | "STOPPED",
) => {
clearTimeout(timer);
worker.removeEventListener("statechange", onStateChange);
pendingStops.delete(onStop);
resolve(outcome);
};
const onStateChange = () => {
if (worker.state === "activated") finish("ACTIVATED");
else if (worker.state === "redundant") finish("INSTALL_FAILED");
};
const onStop = () => finish("STOPPED");
const timer = setTimeout(
() => finish("INSTALL_TIMEOUT"),
SERVICE_WORKER_BOUNDS.installDeadlineMs,
);
pendingStops.add(onStop);
worker.addEventListener("statechange", onStateChange);
// The worker may have settled before this listener existed.
onStateChange();
});
}
function attachMessageListener(container: ServiceWorkerContainer): void {
if (messageListener) return;
messageListener = (event: MessageEvent) => {
@@ -239,6 +288,13 @@ export function createServiceWorkerPageController(
observe("client_drain", rejected ? "BLOCKED" : "DRAINED");
return;
}
// R-6.3. Sent to every tab once any tab's activation committed.
if (
parsed.message.kind === "ACTIVATED_RELOAD_REQUIRED" &&
isExpectedWorkerSource(event.source)
) {
notify(reloadRequiredListeners);
}
observe("message", parsed.message.kind);
};
container.addEventListener("message", messageListener);
@@ -261,6 +317,35 @@ export function createServiceWorkerPageController(
);
}
/**
* R-6.3. An update found by the periodic check (or by another tab) reaches
* `waiting` without any message, so the registration's own events are
* watched. A first install has no active worker and activates on its own,
* so it is never announced as waiting.
*/
function watchForUpdates(watched: ServiceWorkerRegistration): void {
if (updateFoundListener) return;
let lastWatched: ServiceWorker | null = null;
const watchInstalling = () => {
const worker = watched.installing;
if (!worker || worker === lastWatched) return;
lastWatched = worker;
worker.addEventListener("statechange", () => {
if (
worker.state === "installed" &&
watched.waiting === worker &&
watched.active
) {
notify(updateWaitingListeners);
}
});
};
updateFoundListener = watchInstalling;
watched.addEventListener("updatefound", updateFoundListener);
// The update may have been found before this listener existed.
watchInstalling();
}
function scheduleUpdateChecks(): void {
// §17.14. At most one check per 6 hours, and none while the page is hidden.
if (updateTimer) return;
@@ -317,6 +402,18 @@ export function createServiceWorkerPageController(
const onMessage = (event: MessageEvent) => {
const parsed = parseServiceWorkerMessage(event.data);
if (!parsed.ok) return;
const kind = parsed.message.kind;
// R-6.1. Only this request's replies are considered. Any other
// message (SYNC_WAKE_OBSERVED, a drain request, another command's
// result) is not a reply and must not end the activation.
if (
parsed.message.nonce !== nonce ||
(kind !== "ACTIVATE_REJECTED" &&
kind !== "ACTIVATE_ACCEPTED" &&
kind !== "ACTIVATED_RELOAD_REQUIRED")
) {
return;
}
if (
parsed.message.targetBuildId !== undefined &&
parsed.message.targetBuildId !== dependencies.buildId
@@ -331,25 +428,21 @@ export function createServiceWorkerPageController(
finish(Object.freeze({ kind: "PROTOCOL_MISMATCH" as const }));
return;
}
if (registration?.waiting !== waiting) {
// R-6.1. ACCEPTED and RELOAD_REQUIRED are sent after skipWaiting(),
// so the registration may already show this worker as active.
const committed = kind !== "ACTIVATE_REJECTED";
if (
registration?.waiting !== waiting &&
!(committed && registration?.active === waiting)
) {
finish(Object.freeze({ kind: "PROTOCOL_MISMATCH" as const }));
return;
}
if (
parsed.message.kind === "ACTIVATE_REJECTED" &&
parsed.message.nonce === nonce
) {
finish(Object.freeze({ kind: "BLOCKED_DIRTY_CLIENT" as const }));
return;
}
if (
parsed.message.kind === "ACTIVATED_RELOAD_REQUIRED" &&
parsed.message.nonce === nonce
) {
finish(
Object.freeze({ kind: "ACTIVATED_RELOAD_REQUIRED" as const }),
);
}
finish(
committed
? Object.freeze({ kind: "ACTIVATED_RELOAD_REQUIRED" as const })
: Object.freeze({ kind: "BLOCKED_DIRTY_CLIENT" as const }),
);
};
const onStop = () =>
finish(Object.freeze({ kind: "FAILED" as const, code: "STOPPED" }));
@@ -477,10 +570,45 @@ export function createServiceWorkerPageController(
dependencies.container.removeEventListener("message", messageListener);
messageListener = null;
}
if (updateFoundListener && registration) {
registration.removeEventListener("updatefound", updateFoundListener);
updateFoundListener = null;
}
reloadRequiredListeners.clear();
updateWaitingListeners.clear();
nonces.clear();
}
return Object.freeze({ start, requestActivation, resetOwnedCaches, stop });
return Object.freeze({
start,
requestActivation,
resetOwnedCaches,
stop,
onReloadRequired: (listener: () => void) =>
subscribe(reloadRequiredListeners, listener),
onUpdateWaiting: (listener: () => void) =>
subscribe(updateWaitingListeners, listener),
});
}
function subscribe(
listeners: Set<() => void>,
listener: () => void,
): () => void {
listeners.add(listener);
return () => {
listeners.delete(listener);
};
}
function notify(listeners: ReadonlySet<() => void>): void {
for (const listener of [...listeners]) {
try {
listener();
} catch {
// A failing subscriber cannot break the message or event handler.
}
}
}
function canPostMessage(
@@ -247,10 +247,17 @@ async function storeAsset(
if (response.status !== 200 || response.type === "opaque") {
return rejected("STATUS_INVALID");
}
const contentType = response.headers.get("content-type") ?? "";
const contentType =
response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() ??
"";
const expectedType = asset.contentType.toLowerCase();
if (
contentType.split(";", 1)[0]?.trim().toLowerCase() !==
asset.contentType.toLowerCase()
contentType !== expectedType &&
// R-6.5. Servers still send `application/javascript` for `.js`.
!(
JAVASCRIPT_MIME_TYPES.has(contentType) &&
JAVASCRIPT_MIME_TYPES.has(expectedType)
)
) {
return rejected("CONTENT_TYPE_INVALID");
}
@@ -289,6 +296,26 @@ async function storeAsset(
return null;
}
/** WHATWG MIME Sniffing: every essence that denotes a JavaScript MIME type. */
const JAVASCRIPT_MIME_TYPES: ReadonlySet<string> = new Set([
"application/ecmascript",
"application/javascript",
"application/x-ecmascript",
"application/x-javascript",
"text/ecmascript",
"text/javascript",
"text/javascript1.0",
"text/javascript1.1",
"text/javascript1.2",
"text/javascript1.3",
"text/javascript1.4",
"text/javascript1.5",
"text/jscript",
"text/livescript",
"text/x-ecmascript",
"text/x-javascript",
]);
const ABORTED = Symbol("service-worker-install-aborted");
async function abortable<Value>(
@@ -317,8 +344,12 @@ async function readBoundedBody(
| Readonly<{ ok: false; code: "BYTES_MISMATCH" | "FETCH_FAILED" }>
> {
const declaredLength = response.headers.get("content-length");
// R-6.5. With a content-encoding the declared length is the encoded size,
// while the stream yields decoded bytes. The decoded count and sha256 below
// are the real checks.
if (
declaredLength !== null &&
!response.headers.has("content-encoding") &&
/^\d+$/u.test(declaredLength) &&
Number(declaredLength) !== expectedBytes
) {
@@ -2366,11 +2366,21 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
);
}
function purgePartitionRecords(
/**
* R-5.4. A partition purge (session end, logout, account deletion) exists to
* remove everything, so it deletes by key and never stops on a row it cannot
* read: failing closed here left personal data on the device for good. Rows
* that fail validation are counted and reported as one CORRUPT_DATA
* observation per batch. Per-row budget arithmetic is dropped too; the
* budget is reset to zero in the transaction that finds every store empty.
* Between batches it can only read high, which blocks writes, never admits.
*/
async function purgePartitionRecords(
input: IndexedDbLifecycleBatchInput,
deadline: number,
): Promise<BrowserDataResult<IndexedDbLifecycleBatchReceipt>> {
return runTransaction(
let corruptRows = 0;
const result = await runTransaction<IndexedDbLifecycleBatchReceipt>(
[
dependencies.recordStore,
dependencies.governanceStore,
@@ -2486,47 +2496,30 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
walkPurge(
receipts.openCursor(),
({ cursor, resume }) => {
if (!isStoredReceipt(cursor.value)) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
// `fail` aborts, so the pump has nowhere to go.
return { kind: "SUSPEND" };
}
scannedRows += 1;
if (!isStoredReceipt(cursor.value)) corruptRows += 1;
const deletion = receipts.delete(cursor.primaryKey);
deletion.onerror = () =>
context.requestFailed(deletion.error);
deletion.onsuccess = () => {
const budgetRequest = governance.get(
INDEXEDDB_DATASET_BUDGET_KEY,
);
budgetRequest.onerror = () =>
context.requestFailed(budgetRequest.error);
budgetRequest.onsuccess = () => {
if (
!isStoredDatasetBudget(budgetRequest.result) ||
budgetRequest.result.receiptCount < 1
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
}
const storedBudgetRequest = governance.put({
...budgetRequest.result,
receiptCount:
budgetRequest.result.receiptCount - 1,
} satisfies StoredDatasetBudget);
storedBudgetRequest.onerror = () =>
context.requestFailed(
storedBudgetRequest.error,
);
storedBudgetRequest.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
};
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
return { kind: "SUSPEND" };
},
() => succeed("COMPLETE", false),
() => {
// Every store above is empty in this same transaction, so zero
// is exact, and a budget row that had drifted is healed.
const budgetReset = governance.put({
bindingKey: INDEXEDDB_DATASET_BUDGET_KEY,
budgetVersion: 1,
usedBytes: 0,
receiptCount: 0,
} satisfies StoredDatasetBudget);
budgetReset.onerror = () =>
context.requestFailed(budgetReset.error);
budgetReset.onsuccess = () => succeed("COMPLETE", false);
},
);
};
@@ -2534,46 +2527,21 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
walkPurge(
retention.openCursor(),
({ cursor, resume }) => {
scannedRows += 1;
if (
!isStoredRetentionRecord(
cursor.value,
String(cursor.primaryKey),
)
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return { kind: "SUSPEND" };
corruptRows += 1;
}
scannedRows += 1;
const measuredBytes = cursor.value.measuredBytes;
const budgetRequest = governance.get(
INDEXEDDB_DATASET_BUDGET_KEY,
);
budgetRequest.onerror = () =>
context.requestFailed(budgetRequest.error);
budgetRequest.onsuccess = () => {
if (
!isStoredDatasetBudget(budgetRequest.result) ||
budgetRequest.result.usedBytes < measuredBytes
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
}
const deletion = retention.delete(cursor.primaryKey);
deletion.onerror = () =>
context.requestFailed(deletion.error);
deletion.onsuccess = () => {
const budgetWrite = governance.put({
...budgetRequest.result,
usedBytes:
budgetRequest.result.usedBytes - measuredBytes,
} satisfies StoredDatasetBudget);
budgetWrite.onerror = () =>
context.requestFailed(budgetWrite.error);
budgetWrite.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
};
const deletion = retention.delete(cursor.primaryKey);
deletion.onerror = () =>
context.requestFailed(deletion.error);
deletion.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
return { kind: "SUSPEND" };
},
@@ -2584,66 +2552,32 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
walkPurge(
records.openCursor(),
({ cursor, resume }) => {
if (!isStoredRecord(cursor.value)) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return { kind: "SUSPEND" };
}
scannedRows += 1;
const key = cursor.value.key;
const key = cursor.primaryKey;
const recordCorrupt = !isStoredRecord(cursor.value);
const sidecarRequest = retention.get(key);
sidecarRequest.onerror = () =>
context.requestFailed(sidecarRequest.error);
sidecarRequest.onsuccess = () => {
if (
recordCorrupt ||
!isStoredRetentionRecord(
sidecarRequest.result,
key,
String(key),
)
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
corruptRows += 1;
}
const measuredBytes =
sidecarRequest.result.measuredBytes;
const budgetRequest = governance.get(
INDEXEDDB_DATASET_BUDGET_KEY,
);
budgetRequest.onerror = () =>
context.requestFailed(budgetRequest.error);
budgetRequest.onsuccess = () => {
if (
!isStoredDatasetBudget(budgetRequest.result) ||
budgetRequest.result.usedBytes < measuredBytes
) {
context.fail(corruptFailure("INDEXEDDB_WRITE"));
return;
}
const recordDelete = records.delete(key);
recordDelete.onerror = () =>
context.requestFailed(recordDelete.error);
recordDelete.onsuccess = () => {
const sidecarDelete = retention.delete(key);
sidecarDelete.onerror = () =>
context.requestFailed(sidecarDelete.error);
sidecarDelete.onsuccess = () => {
const storedBudgetRequest = governance.put({
bindingKey: INDEXEDDB_DATASET_BUDGET_KEY,
budgetVersion: 1,
usedBytes:
budgetRequest.result.usedBytes -
measuredBytes,
receiptCount:
budgetRequest.result.receiptCount,
} satisfies StoredDatasetBudget);
storedBudgetRequest.onerror = () =>
context.requestFailed(
storedBudgetRequest.error,
);
storedBudgetRequest.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
};
const recordDelete = records.delete(key);
recordDelete.onerror = () =>
context.requestFailed(recordDelete.error);
recordDelete.onsuccess = () => {
const sidecarDelete = retention.delete(key);
sidecarDelete.onerror = () =>
context.requestFailed(sidecarDelete.error);
sidecarDelete.onsuccess = () => {
deletedRows += 1;
resume({ kind: "CONTINUE" });
};
};
};
@@ -2653,6 +2587,16 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
);
},
);
if (corruptRows > 0) {
observe({
operation: "INDEXEDDB_WRITE",
outcome: "FAILED",
schemaVersion: dependencies.schemaVersion,
countBucket: countBucket(corruptRows),
failureCode: "CORRUPT_DATA",
});
}
return result;
}
async function enforceLifecycleBatch(
@@ -33,6 +33,7 @@ import {
} from "../../platform/indexeddb-transaction.ts";
import { mapIndexedDbException } from "../indexeddb/indexeddb-failure.ts";
import { isValidOpfsStorageScope } from "./opfs-policy.ts";
import { isPreparedObject } from "./opfs-prepared-object.ts";
export type IndexedDbOpfsJournalDependencies = Readonly<{
authorityToken: string;
@@ -1607,118 +1608,6 @@ function isChunkReference(
);
}
/**
* STO-01 expand phase. v1 prepared objects stay readable through the rollback
* window; v2 additionally carries a transaction-unique physical fencing token.
*/
function isSupportedPhysicalSchema(value: object): boolean {
const record = value as Record<string, unknown>;
if (record.physicalSchemaVersion === 1) return true;
return (
record.physicalSchemaVersion === 2 &&
typeof record.physicalGenerationId === "string" &&
/^[0-9a-f]{32}$/u.test(record.physicalGenerationId)
);
}
function isPreparedObject(value: unknown): value is OpfsPreparedObject {
if (
!value ||
typeof value !== "object" ||
!("physicalSchemaVersion" in value) ||
!isSupportedPhysicalSchema(value) ||
!("descriptor" in value) ||
!value.descriptor ||
typeof value.descriptor !== "object" ||
!("chunks" in value) ||
!Array.isArray(value.chunks)
) {
return false;
}
const descriptor = value.descriptor as Record<string, unknown>;
const integrity =
descriptor.integrity && typeof descriptor.integrity === "object"
? (descriptor.integrity as Record<string, unknown>)
: null;
if (
typeof descriptor.objectId !== "string" ||
!SAFE_BOUNDARY_ID.test(descriptor.objectId) ||
!descriptor.scope ||
typeof descriptor.scope !== "object" ||
!isValidOpfsStorageScope(descriptor.scope as OpfsStorageScope) ||
typeof descriptor.generation !== "number" ||
!Number.isSafeInteger(descriptor.generation) ||
descriptor.generation < 1 ||
typeof descriptor.byteLength !== "number" ||
!Number.isSafeInteger(descriptor.byteLength) ||
descriptor.byteLength < 0 ||
typeof descriptor.mediaType !== "string" ||
descriptor.mediaType.length < 1 ||
typeof descriptor.createdAtEpochMs !== "number" ||
!Number.isSafeInteger(descriptor.createdAtEpochMs) ||
descriptor.createdAtEpochMs < 0 ||
!integrity ||
integrity.algorithm !== "SHA-256-TREE-V1" ||
typeof integrity.rootDigestHex !== "string" ||
!SHA256_HEX.test(integrity.rootDigestHex) ||
typeof integrity.chunkSizeBytes !== "number" ||
!Number.isSafeInteger(integrity.chunkSizeBytes) ||
integrity.chunkSizeBytes < 1 ||
!descriptor.storagePolicy ||
typeof descriptor.storagePolicy !== "object"
) {
return false;
}
try {
assertValidStoragePolicy(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"],
);
} catch {
return false;
}
if (
(descriptor.scope as OpfsStorageScope).namespace !==
(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"]
).namespace
) {
return false;
}
let totalBytes = 0;
for (let index = 0; index < value.chunks.length; index += 1) {
const chunk = value.chunks[index] as unknown;
if (
!chunk ||
typeof chunk !== "object" ||
!("sequence" in chunk) ||
chunk.sequence !== index ||
!("byteLength" in chunk) ||
typeof chunk.byteLength !== "number" ||
!Number.isSafeInteger(chunk.byteLength) ||
chunk.byteLength < 1 ||
chunk.byteLength > integrity.chunkSizeBytes ||
!("digestHex" in chunk) ||
typeof chunk.digestHex !== "string" ||
!SHA256_HEX.test(chunk.digestHex)
) {
return false;
}
if (
index < value.chunks.length - 1 &&
chunk.byteLength !== integrity.chunkSizeBytes
) {
return false;
}
totalBytes += chunk.byteLength;
}
return (
totalBytes === descriptor.byteLength &&
value.chunks.length ===
Math.ceil(descriptor.byteLength / integrity.chunkSizeBytes)
);
}
function stableJson(value: unknown): string {
if (
value === null ||
@@ -1096,25 +1096,69 @@ export function createOpfsByteStoreAdapter(
0,
now() - policy.orphanGracePeriodMs,
);
const candidates = await dependencies.worker.listOrphanCandidates(
dependencies.scope,
olderThanEpochMs,
policy.orphanGcBatchSize,
signal,
);
if (!candidates.ok) return candidates;
if (!candidates.value.safeToSweep) {
return browserDataSuccess({
inspected: 0,
deleted: 0,
status: "STAGING_STATE_UNREADABLE",
});
}
let inspected = 0;
let deleted = 0;
for (const digestHex of candidates.value.digests) {
if (signal?.aborted) {
return browserDataFailure("ABORTED", "OBJECT_RECONCILE");
// R-5.1. Candidates include committed chunks, so a page can be all
// referenced. The scan pages on by digest cursor until it runs out or the
// deadline stops it.
// ponytail: every reconcile restarts at the lowest digest; if checking the
// referenced chunks alone outlasts the budget, keep the cursor across calls.
let afterDigest: string | undefined;
for (;;) {
const candidates = await dependencies.worker.listOrphanCandidates(
dependencies.scope,
olderThanEpochMs,
policy.orphanGcBatchSize,
signal,
afterDigest,
);
if (!candidates.ok) return candidates;
if (!candidates.value.safeToSweep) {
return browserDataSuccess({
inspected,
deleted,
status: "STAGING_STATE_UNREADABLE",
});
}
for (const digestHex of candidates.value.digests) {
if (signal?.aborted) {
return browserDataFailure("ABORTED", "OBJECT_RECONCILE");
}
if (now() >= deadline) {
return browserDataSuccess({
inspected,
deleted,
status: "DEADLINE_REACHED",
});
}
inspected += 1;
const referenced = await dependencies.journal.isChunkReferenced(
dependencies.scope,
digestHex,
);
if (!referenced.ok) {
return rebaseFailure(referenced.error, "OBJECT_RECONCILE");
}
if (referenced.value) continue;
const removal = await dependencies.worker.deleteOrphanChunk(
dependencies.scope,
digestHex,
olderThanEpochMs,
signal,
);
if (!removal.ok) return removal;
if (removal.value.skippedUnsafe) {
return browserDataSuccess({
inspected,
deleted,
status: "STAGING_STATE_UNREADABLE",
});
}
if (removal.value.deleted) deleted += 1;
}
afterDigest = candidates.value.digests.at(-1);
if (!candidates.value.moreAvailable || afterDigest === undefined) {
return browserDataSuccess({ inspected, deleted, status: "COMPLETED" });
}
if (now() >= deadline) {
return browserDataSuccess({
@@ -1123,39 +1167,7 @@ export function createOpfsByteStoreAdapter(
status: "DEADLINE_REACHED",
});
}
inspected += 1;
const referenced = await dependencies.journal.isChunkReferenced(
dependencies.scope,
digestHex,
);
if (!referenced.ok) {
return rebaseFailure(referenced.error, "OBJECT_RECONCILE");
}
if (referenced.value) continue;
const removal = await dependencies.worker.deleteOrphanChunk(
dependencies.scope,
digestHex,
olderThanEpochMs,
signal,
);
if (!removal.ok) return removal;
if (removal.value.skippedUnsafe) {
return browserDataSuccess({
inspected,
deleted,
status: "STAGING_STATE_UNREADABLE",
});
}
if (removal.value.deleted) deleted += 1;
}
return browserDataSuccess({
inspected,
deleted,
status:
candidates.value.moreAvailable
? "DEADLINE_REACHED"
: "COMPLETED",
});
}
}
+10
View File
@@ -14,6 +14,12 @@ export type OpfsRuntimePolicy = Readonly<{
maxObjectBytes: number;
maxChunkCount: number;
rpcTimeoutMs: number;
/**
* R-5.3 (D-3). How long a request may queue for the origin mutation lock.
* Another context's put holds that lock for its whole upload, so this wait
* is bounded on its own and never counted against `rpcTimeoutMs`.
*/
mutationLockWaitTimeoutMs: number;
reconciliationBudgetMs: number;
reconciliationBatchSize: number;
orphanGracePeriodMs: number;
@@ -49,6 +55,7 @@ export const DEFAULT_OPFS_RUNTIME_POLICY: OpfsRuntimePolicy = Object.freeze({
maxObjectBytes: 2 * 1024 * 1024 * 1024,
maxChunkCount: 512,
rpcTimeoutMs: 60_000,
mutationLockWaitTimeoutMs: 10 * 60_000,
reconciliationBudgetMs: 5_000,
reconciliationBatchSize: 100,
orphanGracePeriodMs: 24 * 60 * 60 * 1_000,
@@ -84,6 +91,9 @@ export function assertOpfsRuntimePolicy(policy: OpfsRuntimePolicy): void {
policy.maxObjectBytes > policy.chunkSizeBytes * policy.maxChunkCount ||
!Number.isSafeInteger(policy.rpcTimeoutMs) ||
policy.rpcTimeoutMs < 1_000 ||
!Number.isSafeInteger(policy.mutationLockWaitTimeoutMs) ||
policy.mutationLockWaitTimeoutMs < 1_000 ||
policy.mutationLockWaitTimeoutMs > 60 * 60_000 ||
!Number.isSafeInteger(policy.reconciliationBudgetMs) ||
policy.reconciliationBudgetMs < 1 ||
policy.reconciliationBudgetMs > 60_000 ||
@@ -0,0 +1,131 @@
import type {
OpfsPreparedObject,
OpfsStorageScope,
} from "../../../application/ports/browser-file-storage/opfs-ports.ts";
import { assertValidStoragePolicy } from "../../../application/ports/browser-file-storage/shared.ts";
import { isValidOpfsStorageScope } from "./opfs-policy.ts";
const OPAQUE_OBJECT_ID = /^[A-Za-z0-9_-]{8,128}$/u;
const SHA256_HEX = /^[a-f0-9]{64}$/u;
/**
* STO-01 expand phase. v1 prepared objects stay readable through the rollback
* window; v2 additionally carries a transaction-unique physical fencing token.
*/
function isSupportedPhysicalSchema(value: object): boolean {
const record = value as Record<string, unknown>;
if (record.physicalSchemaVersion === 1) return true;
return (
record.physicalSchemaVersion === 2 &&
typeof record.physicalGenerationId === "string" &&
/^[0-9a-f]{32}$/u.test(record.physicalGenerationId)
);
}
/**
* R-5.5. The one prepared-object validator for the page, the journal and the
* worker. An object is checked against itself, including its own
* `chunkSizeBytes`, never against the current runtime policy: the policy
* governs new writes only (validateObjectWriteInput, BEGIN_PUT, APPEND_CHUNK),
* so changing the chunk size or another limit cannot make stored objects
* unreadable or unreconcilable.
*/
export function isPreparedObject(
value: unknown,
): value is OpfsPreparedObject {
if (
!value ||
typeof value !== "object" ||
!("physicalSchemaVersion" in value) ||
!isSupportedPhysicalSchema(value) ||
!("descriptor" in value) ||
!value.descriptor ||
typeof value.descriptor !== "object" ||
!("chunks" in value) ||
!Array.isArray(value.chunks)
) {
return false;
}
const descriptor = value.descriptor as Record<string, unknown>;
const integrity =
descriptor.integrity && typeof descriptor.integrity === "object"
? (descriptor.integrity as Record<string, unknown>)
: null;
if (
typeof descriptor.objectId !== "string" ||
!OPAQUE_OBJECT_ID.test(descriptor.objectId) ||
!descriptor.scope ||
typeof descriptor.scope !== "object" ||
!isValidOpfsStorageScope(descriptor.scope as OpfsStorageScope) ||
typeof descriptor.generation !== "number" ||
!Number.isSafeInteger(descriptor.generation) ||
descriptor.generation < 1 ||
typeof descriptor.byteLength !== "number" ||
!Number.isSafeInteger(descriptor.byteLength) ||
descriptor.byteLength < 0 ||
typeof descriptor.mediaType !== "string" ||
descriptor.mediaType.length < 1 ||
typeof descriptor.createdAtEpochMs !== "number" ||
!Number.isSafeInteger(descriptor.createdAtEpochMs) ||
descriptor.createdAtEpochMs < 0 ||
!integrity ||
integrity.algorithm !== "SHA-256-TREE-V1" ||
typeof integrity.rootDigestHex !== "string" ||
!SHA256_HEX.test(integrity.rootDigestHex) ||
typeof integrity.chunkSizeBytes !== "number" ||
!Number.isSafeInteger(integrity.chunkSizeBytes) ||
integrity.chunkSizeBytes < 1 ||
!descriptor.storagePolicy ||
typeof descriptor.storagePolicy !== "object"
) {
return false;
}
try {
assertValidStoragePolicy(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"],
);
} catch {
return false;
}
if (
(descriptor.scope as OpfsStorageScope).namespace !==
(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"]
).namespace
) {
return false;
}
let totalBytes = 0;
for (let index = 0; index < value.chunks.length; index += 1) {
const chunk = value.chunks[index] as unknown;
if (
!chunk ||
typeof chunk !== "object" ||
!("sequence" in chunk) ||
chunk.sequence !== index ||
!("byteLength" in chunk) ||
typeof chunk.byteLength !== "number" ||
!Number.isSafeInteger(chunk.byteLength) ||
chunk.byteLength < 1 ||
chunk.byteLength > integrity.chunkSizeBytes ||
!("digestHex" in chunk) ||
typeof chunk.digestHex !== "string" ||
!SHA256_HEX.test(chunk.digestHex)
) {
return false;
}
if (
index < value.chunks.length - 1 &&
chunk.byteLength !== integrity.chunkSizeBytes
) {
return false;
}
totalBytes += chunk.byteLength;
}
return (
totalBytes === descriptor.byteLength &&
value.chunks.length ===
Math.ceil(descriptor.byteLength / integrity.chunkSizeBytes)
);
}
+12 -27
View File
@@ -15,7 +15,9 @@ import {
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import type { OpfsRuntimePolicy } from "./opfs-policy.ts";
import { isPreparedObject } from "./opfs-prepared-object.ts";
import {
OPFS_LOCK_WAITING_REQUEST_KINDS,
OPFS_WORKER_PROTOCOL_VERSION,
} from "./opfs-worker-protocol.ts";
import type {
@@ -167,13 +169,19 @@ export function createOpfsWorkerGateway(
reject(new OpfsRpcError("ABORTED"));
};
signal?.addEventListener("abort", abort, { once: true });
// R-5.3. Time queued behind another context's lock holder is the
// worker's to bound; it must not eat this request's own RPC budget.
const timeoutMs = OPFS_LOCK_WAITING_REQUEST_KINDS.has(request.kind)
? dependencies.policy.rpcTimeoutMs +
dependencies.policy.mutationLockWaitTimeoutMs
: dependencies.policy.rpcTimeoutMs;
const timeout = setTimeout(() => {
const item = pending.get(requestId);
if (!item) return;
pending.delete(requestId);
item.removeAbortListener();
reject(new OpfsRpcError("UNAVAILABLE"));
}, dependencies.policy.rpcTimeoutMs);
}, timeoutMs);
pending.set(requestId, {
// STO-07. The expected kind is stored so a reply for a different
// operation can never satisfy this request.
@@ -440,6 +448,7 @@ export function createOpfsWorkerGateway(
olderThanEpochMs: number,
maxEntries: number,
signal?: AbortSignal,
afterDigest?: string,
) {
return await invoke(
"OBJECT_RECONCILE",
@@ -448,6 +457,7 @@ export function createOpfsWorkerGateway(
scope,
olderThanEpochMs,
maxEntries,
...(afterDigest === undefined ? {} : { afterDigest }),
},
signal,
[],
@@ -639,20 +649,6 @@ function parseCapabilities(value: unknown): OpfsCapabilities | null {
return value as OpfsCapabilities;
}
/**
* STO-01 expand phase. v1 prepared objects stay readable through the rollback
* window; v2 additionally carries a transaction-unique physical fencing token.
*/
function isSupportedPhysicalSchema(value: object): boolean {
const record = value as Record<string, unknown>;
if (record.physicalSchemaVersion === 1) return true;
return (
record.physicalSchemaVersion === 2 &&
typeof record.physicalGenerationId === "string" &&
/^[0-9a-f]{32}$/u.test(record.physicalGenerationId)
);
}
function parseCleanupEffect(value: unknown): OpfsCleanupEffect | null {
if (!value || typeof value !== "object") return null;
const kind = (value as Record<string, unknown>).kind;
@@ -662,18 +658,7 @@ function parseCleanupEffect(value: unknown): OpfsCleanupEffect | null {
}
function parsePreparedObject(value: unknown): OpfsPreparedObject | null {
if (
!value ||
typeof value !== "object" ||
!("physicalSchemaVersion" in value) ||
!isSupportedPhysicalSchema(value) ||
!("descriptor" in value) ||
!("chunks" in value) ||
!Array.isArray(value.chunks)
) {
return null;
}
return value as OpfsPreparedObject;
return isPreparedObject(value) ? value : null;
}
function parseOrphanCandidateBatch(
@@ -120,6 +120,12 @@ export type OpfsWorkerRequest =
scope: OpfsStorageScope;
olderThanEpochMs: number;
maxEntries: number;
/**
* R-5.1. Candidates come back in ascending digest order. The next page
* starts strictly after this digest (the last one of the previous page),
* so a batch of still-referenced chunks cannot hide the rest forever.
*/
afterDigest?: string;
}>
| Readonly<{
requestId: string;
@@ -130,6 +136,23 @@ export type OpfsWorkerRequest =
olderThanEpochMs: number;
}>;
/**
* R-5.3 (D-3). Requests the worker may park on the origin mutation lock. The
* worker bounds that wait by `mutationLockWaitTimeoutMs`; the page adds the
* same bound to these requests' RPC timer.
*/
export const OPFS_LOCK_WAITING_REQUEST_KINDS: ReadonlySet<
OpfsWorkerRequest["kind"]
> = new Set([
"BEGIN_PUT",
"ABORT_PUT",
"REMOVE_OBJECT",
"CLEANUP_TRANSACTION",
"FINALIZE_PUT",
"LIST_ORPHAN_CANDIDATES",
"DELETE_ORPHAN_CHUNK",
]);
export type OpfsWorkerRequestBody =
OpfsWorkerRequest extends infer Request
? Request extends OpfsWorkerRequest
@@ -239,6 +262,7 @@ export interface OpfsWorkerGateway {
olderThanEpochMs: number,
maxEntries: number,
signal?: AbortSignal,
afterDigest?: string,
): Promise<BrowserDataResult<OpfsOrphanCandidateBatch>>;
deleteOrphanChunk(
scope: OpfsStorageScope,
+78 -132
View File
@@ -10,11 +10,13 @@ import {
assertValidStoragePolicy,
type BrowserDataFailureCode,
} from "../../../application/ports/browser-file-storage/shared.ts";
import { createAbortableOperation } from "../../platform/abortable-operation.ts";
import {
resolveOpfsRuntimePolicy,
isValidOpfsStorageScope,
type OpfsRuntimePolicy,
} from "./opfs-policy.ts";
import { isPreparedObject } from "./opfs-prepared-object.ts";
import {
OPFS_WORKER_PROTOCOL_VERSION,
} from "./opfs-worker-protocol.ts";
@@ -289,6 +291,7 @@ export function createOpfsWorkerRuntime(
request.scope,
request.olderThanEpochMs,
request.maxEntries,
request.afterDigest,
),
);
case "DELETE_ORPHAN_CHUNK":
@@ -359,7 +362,7 @@ export function createOpfsWorkerRuntime(
pendingBegins.set(transactionKey, beginAbort);
let lease: OpfsMutationLease;
try {
lease = await dependencies.leaseManager!.acquire(beginAbort.signal);
lease = await acquireLease(beginAbort.signal);
} finally {
pendingBegins.delete(transactionKey);
}
@@ -691,7 +694,7 @@ export function createOpfsWorkerRuntime(
async function verifyObject(
expected: OpfsPreparedObject,
): Promise<boolean> {
if (!isPreparedObjectSafe(expected, dependencies.policy)) return false;
if (!isPreparedObject(expected)) return false;
let stored: unknown;
try {
stored = await readJson(manifestPath(expected));
@@ -700,7 +703,7 @@ export function createOpfsWorkerRuntime(
throw error;
}
if (
!isPreparedObjectSafe(stored, dependencies.policy) ||
!isPreparedObject(stored) ||
stableJson(stored) !== stableJson(expected)
) {
return false;
@@ -739,7 +742,7 @@ export function createOpfsWorkerRuntime(
sequence: number,
): Promise<ArrayBuffer> {
if (
!isPreparedObjectSafe(expected, dependencies.policy) ||
!isPreparedObject(expected) ||
!Number.isSafeInteger(sequence) ||
sequence < 0
) {
@@ -776,7 +779,7 @@ export function createOpfsWorkerRuntime(
) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
const prefixDirectory = await getDirectory(
dependencies.root,
@@ -826,7 +829,7 @@ export function createOpfsWorkerRuntime(
throw error;
}
// Every destructive step below runs while the lease is held.
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
return await cleanupTransactionLocked(
scope,
@@ -906,11 +909,11 @@ export function createOpfsWorkerRuntime(
assertWorkerAvailable();
if (
!SAFE_TRANSACTION_ID.test(transactionId) ||
!isPreparedObjectSafe(preparedObject, dependencies.policy)
!isPreparedObject(preparedObject)
) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
const descriptor = preparedObject.descriptor;
const objectDirectory = await getDirectory(
@@ -952,6 +955,7 @@ export function createOpfsWorkerRuntime(
scope: OpfsPreparedObject["descriptor"]["scope"],
olderThanEpochMs: number,
maxEntries: number,
afterDigest: string | undefined,
): Promise<OpfsOrphanCandidateBatch> {
assertWorkerAvailable();
if (
@@ -960,11 +964,13 @@ export function createOpfsWorkerRuntime(
olderThanEpochMs < 0 ||
!Number.isSafeInteger(maxEntries) ||
maxEntries < 1 ||
maxEntries > dependencies.policy.orphanGcBatchSize
maxEntries > dependencies.policy.orphanGcBatchSize ||
(afterDigest !== undefined &&
(typeof afterDigest !== "string" || !SHA256_HEX.test(afterDigest)))
) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
const staged = await stagedChunkDigests(scope);
if (!staged.safeToSweep) {
@@ -991,25 +997,33 @@ export function createOpfsWorkerRuntime(
}
throw error;
}
// R-5.1. Directory order is unspecified, so the scan walks prefixes and
// names in ascending order; that is what makes `afterDigest` a cursor.
const cursor = afterDigest ?? "";
const prefixes = new Map<string, FileSystemDirectoryHandle>();
for await (const [name, handle] of shaRoot.entries()) {
if (handle.kind !== "directory" || name < cursor.slice(0, 2)) continue;
prefixes.set(name, handle as FileSystemDirectoryHandle);
}
const candidates: string[] = [];
outer: for await (const [, prefixHandle] of shaRoot.entries()) {
if (prefixHandle.kind !== "directory") continue;
const prefixDirectory =
prefixHandle as FileSystemDirectoryHandle;
for await (const [name, handle] of prefixDirectory.entries()) {
outer: for (const prefix of [...prefixes.keys()].sort()) {
const files = new Map<string, FileSystemFileHandle>();
for await (const [name, handle] of prefixes.get(prefix)!.entries()) {
if (handle.kind !== "file") continue;
const digestHex = name.endsWith(".bin")
? name.slice(0, -4)
: "";
if (
!SHA256_HEX.test(digestHex) ||
digestHex <= cursor ||
staged.digests.has(digestHex)
) {
continue;
}
const file = await (
handle as FileSystemFileHandle
).getFile();
files.set(digestHex, handle as FileSystemFileHandle);
}
for (const digestHex of [...files.keys()].sort()) {
const file = await files.get(digestHex)!.getFile();
if (file.lastModified > olderThanEpochMs) continue;
candidates.push(digestHex);
if (candidates.length > maxEntries) break outer;
@@ -1039,7 +1053,7 @@ export function createOpfsWorkerRuntime(
) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await dependencies.leaseManager!.acquire();
const lease = await acquireLease();
try {
const staged = await stagedChunkDigests(scope);
if (!staged.safeToSweep) {
@@ -1147,7 +1161,7 @@ export function createOpfsWorkerRuntime(
}
if (
record.phase === "FILES_READY" &&
isPreparedObjectSafe(record.preparedObject, dependencies.policy) &&
isPreparedObject(record.preparedObject) &&
sameScope(record.preparedObject.descriptor.scope, scope)
) {
const prepared = record.preparedObject;
@@ -1207,6 +1221,21 @@ export function createOpfsWorkerRuntime(
);
await directory.removeEntry(fileName);
} else {
// R-5.2. A dedup hit must restart the chunk's grace period. Orphan GC
// reads "not referenced" from the page journal and deletes in the
// worker, so another tab's GC can hold a stale answer for a chunk that
// this put is about to reference once staging is gone. An atomic
// rewrite of the identical bytes refreshes lastModified, and readers of
// the committed chunk see either copy, never a partial file.
const { directory, fileName } = await resolveFileParent(
dependencies.root,
path,
false,
);
await writeWithAtomicWritable(
await directory.getFileHandle(fileName),
bytes,
);
return;
}
} catch (error) {
@@ -1285,6 +1314,35 @@ export function createOpfsWorkerRuntime(
throw new OpfsRuntimeFailure("UNSUPPORTED");
}
}
/**
* R-5.3 (D-3). The lock stays origin-wide so GC and dedup keep seeing one
* writer; only the wait is bounded. A request still queued after
* `mutationLockWaitTimeoutMs` leaves the queue and fails BLOCKED (retryable).
*/
async function acquireLease(
signal?: AbortSignal,
): Promise<OpfsMutationLease> {
const wait = createAbortableOperation({
signal,
timeoutMs: dependencies.policy.mutationLockWaitTimeoutMs,
});
// A lease granted after the wait already ended is handed straight back.
const outcome = await wait.race(
dependencies.leaseManager!.acquire(wait.signal),
(lease) => lease.release(),
);
wait.close();
if (outcome.kind === "VALUE") return outcome.value;
if (outcome.kind === "REJECTED") throw outcome.reason;
if (outcome.terminal === "DEADLINE") {
throw new OpfsRuntimeFailure("BLOCKED", true);
}
throw new OpfsRuntimeFailure(
outcome.terminal === "CALLER_ABORT" ? "ABORTED" : "UNAVAILABLE",
outcome.terminal !== "CALLER_ABORT",
);
}
}
export function installOpfsWorkerMessageHandler(
@@ -1670,118 +1728,6 @@ function stableJson(value: unknown): string {
throw new OpfsRuntimeFailure("CORRUPT_DATA");
}
/**
* STO-01 expand phase. v1 prepared objects stay readable through the rollback
* window; v2 additionally carries a transaction-unique physical fencing token.
*/
function isSupportedPhysicalSchema(value: object): boolean {
const record = value as Record<string, unknown>;
if (record.physicalSchemaVersion === 1) return true;
return (
record.physicalSchemaVersion === 2 &&
typeof record.physicalGenerationId === "string" &&
/^[0-9a-f]{32}$/u.test(record.physicalGenerationId)
);
}
function isPreparedObjectSafe(
value: unknown,
policy: OpfsRuntimePolicy,
): value is OpfsPreparedObject {
if (
!value ||
typeof value !== "object" ||
!("physicalSchemaVersion" in value) ||
!isSupportedPhysicalSchema(value) ||
!("descriptor" in value) ||
!value.descriptor ||
typeof value.descriptor !== "object" ||
!("chunks" in value) ||
!Array.isArray(value.chunks)
) {
return false;
}
const descriptor = value.descriptor as Record<string, unknown>;
const integrity =
descriptor.integrity && typeof descriptor.integrity === "object"
? (descriptor.integrity as Record<string, unknown>)
: null;
if (
typeof descriptor.objectId !== "string" ||
!policy.isObjectIdAllowed(descriptor.objectId) ||
!("scope" in descriptor) ||
!descriptor.scope ||
typeof descriptor.scope !== "object" ||
!isValidOpfsStorageScope(
descriptor.scope as OpfsPreparedObject["descriptor"]["scope"],
) ||
(descriptor.scope as OpfsPreparedObject["descriptor"]["scope"])
.namespace !==
(descriptor.storagePolicy as
| OpfsPreparedObject["descriptor"]["storagePolicy"]
| undefined)?.namespace ||
typeof descriptor.generation !== "number" ||
!Number.isSafeInteger(descriptor.generation) ||
descriptor.generation < 1 ||
typeof descriptor.byteLength !== "number" ||
!Number.isSafeInteger(descriptor.byteLength) ||
descriptor.byteLength < 0 ||
descriptor.byteLength > policy.maxObjectBytes ||
typeof descriptor.mediaType !== "string" ||
!policy.isMediaTypeAllowed(descriptor.mediaType) ||
typeof descriptor.createdAtEpochMs !== "number" ||
!Number.isSafeInteger(descriptor.createdAtEpochMs) ||
descriptor.createdAtEpochMs < 0 ||
!integrity ||
integrity.algorithm !== "SHA-256-TREE-V1" ||
typeof integrity.rootDigestHex !== "string" ||
!SHA256_HEX.test(integrity.rootDigestHex) ||
integrity.chunkSizeBytes !== policy.chunkSizeBytes ||
!("storagePolicy" in descriptor) ||
!descriptor.storagePolicy ||
typeof descriptor.storagePolicy !== "object" ||
value.chunks.length > policy.maxChunkCount
) {
return false;
}
try {
assertValidStoragePolicy(
descriptor.storagePolicy as OpfsPreparedObject["descriptor"]["storagePolicy"],
);
} catch {
return false;
}
let total = 0;
for (let index = 0; index < value.chunks.length; index += 1) {
const chunk = value.chunks[index] as unknown;
if (
!chunk ||
typeof chunk !== "object" ||
!("sequence" in chunk) ||
chunk.sequence !== index ||
!("byteLength" in chunk) ||
typeof chunk.byteLength !== "number" ||
!Number.isSafeInteger(chunk.byteLength) ||
chunk.byteLength < 1 ||
chunk.byteLength > policy.chunkSizeBytes ||
!("digestHex" in chunk) ||
typeof chunk.digestHex !== "string" ||
!SHA256_HEX.test(chunk.digestHex)
) {
return false;
}
if (index < value.chunks.length - 1 && chunk.byteLength !== policy.chunkSizeBytes) {
return false;
}
total += chunk.byteLength;
}
return (
total === descriptor.byteLength &&
value.chunks.length ===
Math.ceil(descriptor.byteLength / policy.chunkSizeBytes)
);
}
function success(
requestId: string,
kind: OpfsWorkerRequest["kind"],
@@ -343,6 +343,29 @@ export function createWebPushSubscriptionAdapter(
return webPushFailure("ABORTED", "SUBSCRIPTION_RECONCILE");
}
if (reconciled.value.state === "ABSENT") {
// R-6.7. Only a local ACTIVE association (the server lost it) is
// re-registered. A REVOKED or UNASSOCIATED fence with a leftover
// native subscription is a failed logout cleanup or an unfinished
// opt-in; registering it would sign the current account up without
// its own consent, so the native subscription is removed instead.
const association = prepared.value.control.association;
if (association.state !== "ACTIVE") {
const nativeClean = await cleanupNative(
association.state === "UNASSOCIATED"
? null
: association.associationEpoch,
generation,
Object.freeze({ captured: true, subscription: native.value }),
prepared.value,
);
return webPushSuccess(
unavailable(
nativeClean
? "BACKEND_ASSOCIATION_MISSING"
: "NATIVE_UNSUBSCRIBE_AMBIGUOUS",
),
);
}
return await registerAndActivate({
subscription: native.value,
prepared: prepared.value,
+9
View File
@@ -41,6 +41,15 @@ export function createApplication(
const normalized = normalizeColorSchemePreference(preference);
return outputPorts.preferences.write("COLOR_SCHEME", normalized);
},
getLocale(): string | undefined {
const result = outputPorts.preferences.read("LOCALE");
return result.ok && typeof result.value === "string"
? result.value
: undefined;
},
setLocale(locale: string) {
return outputPorts.preferences.write("LOCALE", locale);
},
});
const diagnostics = Object.freeze({
@@ -6,6 +6,13 @@ export type SessionState =
export type SessionGateway = Readonly<{
getState(): SessionState;
/**
* Optional opaque identifier of the signed-in subject. The server-state scope
* fences only when (state, subject) changes, so a token refresh does not clear
* the cache. An authenticated session that returns `null` or omits this is
* treated as possibly switched and still fences on every notification.
*/
getSubject?(): string | null;
subscribe(listener: () => void): () => void;
beginSignIn(returnTo?: string): Promise<void>;
signOut(): Promise<void>;
@@ -54,6 +54,9 @@ export type ApplicationApi = Readonly<{
setColorScheme(
preference: ColorSchemePreference,
): ReturnType<StoragePort["write"]>;
/** The stored locale tag, unvalidated; presentation owns the locale list. */
getLocale(): string | undefined;
setLocale(locale: string): ReturnType<StoragePort["write"]>;
}>;
diagnostics: Readonly<{
reportRenderFailure(report: RenderFailureReport): void;
@@ -130,6 +130,12 @@ export type RealtimeAcceptDisposition =
outcome: "RECOVERED";
reason: RealtimeRecoveryReason;
resumeState: RealtimeRecoveryCheckpoint;
/**
* `false` when the stream's recovery has no transport barrier to confirm
* (SNAPSHOT_ONLY with barrier NONE), so the transport keeps its
* connection. Absent means a barrier is required.
*/
transportBarrierRequired?: boolean;
}>
| Readonly<{
outcome: "RECOVERY_BARRIER_REQUIRED";
+3 -1
View File
@@ -95,7 +95,9 @@ export function deriveAsyncState(signals: AsyncSignals): AsyncState {
? "empty"
: hasData
? "success"
: "initial-loading";
: // Nothing loading, failed or present (a disabled query) is not
// a load in progress.
"empty";
const indicator =
signals.hasMutationEffectUnknown && hasData
+3 -2
View File
@@ -75,8 +75,9 @@ export function createBootReleaseRecovery(
}
/**
* Decides what a failed boot does: a release mismatch may reload exactly once
* per mismatch key; anything else (and a repeated mismatch) shows the failure.
* Decides what a failed boot does: a release mismatch may reload at most once
* per session within the marker TTL; anything else (and any further mismatch)
* shows the failure.
*/
export function decideBootFailure(
error: unknown,
+4 -1
View File
@@ -517,7 +517,10 @@ export async function createRuntimeAdapters(
? {}
: { execution: executionContext.execution }),
});
if (outcome.kind === "UNAUTHENTICATED") {
// R-3.2. Only a server 401 is a session verdict. A request refused before
// dispatch for lack of a credential carries no response metadata; telling
// the owner would overwrite a recovering session and re-fence the scope.
if (outcome.kind === "UNAUTHENTICATED" && outcome.metadata !== undefined) {
authSession.onUnauthenticated();
}
return outcome;
+27 -22
View File
@@ -1,6 +1,7 @@
import { StrictMode, useEffect } from "react";
import { ApplicationProvider } from "../presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../presentation/providers/preference-providers.tsx";
import { ServerStateGenerationProvider } from "../presentation/adapters/query/server-state-generation-provider.tsx";
import { AppRouter } from "../presentation/routes/app-router.tsx";
import type { RuntimeComposition } from "./create-runtime-composition.ts";
@@ -28,28 +29,32 @@ export function RuntimeApplication({
}: Readonly<{ composition: RuntimeComposition }>) {
return (
<StrictMode>
<ServerStateGenerationProvider
store={composition.infrastructure.serverStateGeneration}
scope={composition.infrastructure.serverStateScope}
mutationIntentFactory={
composition.infrastructure.mutationIntentFactory
}
transitionFallback={
<div
aria-busy="true"
className="state-surface state-surface--loading"
data-scope-state="scope-transition"
/>
}
>
<ApplicationProvider application={composition.application}>
<PostMountRuntimeStarter composition={composition} />
<AppRouter
basename={composition.config.build.routerBasePath}
buildId={composition.release.buildId}
/>
</ApplicationProvider>
</ServerStateGenerationProvider>
{/* Preferences sit above the scope fence: a session change remounts
everything below it, and locale/theme must survive that. */}
<ApplicationProvider application={composition.application}>
<PreferenceProviders>
<ServerStateGenerationProvider
store={composition.infrastructure.serverStateGeneration}
scope={composition.infrastructure.serverStateScope}
mutationIntentFactory={
composition.infrastructure.mutationIntentFactory
}
transitionFallback={
<div
aria-busy="true"
className="state-surface state-surface--loading"
data-scope-state="scope-transition"
/>
}
>
<PostMountRuntimeStarter composition={composition} />
<AppRouter
basename={composition.config.build.routerBasePath}
buildId={composition.release.buildId}
/>
</ServerStateGenerationProvider>
</PreferenceProviders>
</ApplicationProvider>
</StrictMode>
);
}
+7
View File
@@ -180,7 +180,14 @@ function validateRestOperation(operation: RestOperationV2): void {
);
}
const isQuery = operation.semantics === "QUERY";
// R-7.4. CSRF need is decided from the method (rest-profiles), so a COMMAND
// must use an unsafe method. Same binding as browser-rpc and the V3 runtime.
if (
!["QUERY", "COMMAND"].includes(operation.semantics) ||
!["SAFE", "IDEMPOTENT", "KEYED_COMMAND", "NON_REPLAYABLE"].includes(
operation.replayPolicy,
) ||
(!isQuery && !["POST", "PUT", "PATCH", "DELETE"].includes(operation.method)) ||
(isQuery && !["GET", "HEAD"].includes(operation.method)) ||
(isQuery && !["SAFE", "IDEMPOTENT"].includes(operation.replayPolicy)) ||
(operation.replayPolicy === "KEYED_COMMAND" &&
+14 -2
View File
@@ -1,3 +1,5 @@
import { isOperationId } from "./operation-id.ts";
export const DIAGNOSTIC_LEVELS = Object.freeze([
"debug",
"info",
@@ -94,8 +96,10 @@ const BOUNDED_CONTEXT_VALUE_POLICIES: Readonly<
/^(?:success|recovered|failed|aborted|SUCCESS|PROBLEM|UNAUTHENTICATED|FORBIDDEN|RATE_LIMITED|CONTRACT_VIOLATION|TRANSPORT_FAILURE|CANCELLED|AUTH_INTEGRATION_FAILURE|FAILED|DEGRADED)$/.test(
value,
),
http_status_group: (value) =>
typeof value === "string" && /^(?:[0-9]xx|none)$/.test(value),
http_status_group: isHttpStatusGroup,
// R-7.5. Not a finite set, but source-controlled topology: the shared
// grammar applies instead of the free-form safe-string pattern.
operation_id: isOperationId,
attempt_count_bucket: (value) =>
typeof value === "string" && /^(?:1|2|3|3-4|5\+)$/.test(value),
duration_bucket: (value) =>
@@ -231,6 +235,14 @@ export function statusGroup(status: number | undefined): string {
: "none";
}
/**
* R-7.5. Exactly the values `statusGroup` produces. Telemetry and diagnostics
* both validate `http_status_group` with it.
*/
export function isHttpStatusGroup(value: unknown): value is string {
return typeof value === "string" && /^(?:[0-9]xx|none)$/.test(value);
}
export function attemptBucket(attemptCount: number): string {
if (attemptCount <= 1) return "1";
if (attemptCount === 2) return "2";
+19 -2
View File
@@ -23,6 +23,14 @@ const SEMANTIC_KEY_ALLOWLIST = Object.freeze(
new Set(["AUTH_MODE", "TELEMETRY_ENABLED"]),
);
/**
* R-7.2. Exact top-level keys whose own keys are feature ids (data), not
* configuration names: `cookie-consent` or `token-wallet` is a feature, not a
* credential. Only the map keys are exempt; anything nested below them is
* still checked.
*/
const FEATURE_ID_KEYED_MAPS = Object.freeze(new Set(["FEATURE_OVERRIDES"]));
export type EnvironmentPhase = "build" | "runtime";
export type EnvironmentDefinition = Readonly<{
phase: EnvironmentPhase;
@@ -82,12 +90,21 @@ export function assertSafeConfigNames(
if (!allowlisted && isForbiddenConfigName(name)) {
throw new Error(`Forbidden client configuration key: ${name}`);
}
if (value && typeof value === "object" && !Array.isArray(value)) {
assertSafeConfigNames(value as Record<string, unknown>, depth + 1);
if (!isPlainNested(value)) continue;
if (depth === 0 && FEATURE_ID_KEYED_MAPS.has(name)) {
for (const entry of Object.values(value)) {
if (isPlainNested(entry)) assertSafeConfigNames(entry, depth + 2);
}
} else {
assertSafeConfigNames(value, depth + 1);
}
}
}
function isPlainNested(value: unknown): value is Record<string, unknown> {
return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}
function isForbiddenConfigName(name: string): boolean {
const upper = name.toUpperCase();
return FORBIDDEN_CONFIG_NAME_FRAGMENTS.some((fragment) =>
+2 -5
View File
@@ -7,6 +7,7 @@
* applies before a contribution may be composed.
*/
import { isOperationId } from "./operation-id.ts";
import { INSTALLED_REST_AUTH_PROFILES } from "./rest-profiles.ts";
import {
defineTrafficBudget,
@@ -234,7 +235,6 @@ const SEM_VER =
/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
const DIGEST = /^sha256:[0-9a-f]{64}$/;
const SOURCE_REVISION = /^[0-9a-f]{7,64}$/;
const OPERATION_ID = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
/** Whitespace and C0/C1 control characters are rejected in an event type. */
function hasControlOrSpace(value: string): boolean {
for (const character of value) {
@@ -386,10 +386,7 @@ function assertHttpContract(
}
const label = `${featureId}/${String(contract.operationId)}`;
if (
typeof contract.operationId !== "string" ||
!OPERATION_ID.test(contract.operationId)
) {
if (!isOperationId(contract.operationId)) {
fail(`${label}: operationId`);
}
if (
+10 -15
View File
@@ -30,23 +30,18 @@ function validBoundedString(value: unknown, maxBytes: number): value is string {
* A caller-supplied value is never trimmed, regenerated or silently dropped:
* an invalid key is a contract violation, because replaying a keyed command
* without its key is exactly the unsafe behaviour the key exists to prevent.
*
* R-7.1. Visible ASCII only: fetch strips surrounding whitespace from header
* values (two keys would collide on the wire) and throws on non-ByteString
* values. Same rule as the realtime `HEADER_SAFE_CURSOR`.
*/
const IDEMPOTENCY_KEY = /^[\x21-\x7e]+$/u;
export function isValidIdempotencyKey(value: unknown): value is string {
if (
!validBoundedString(
value,
MUTATION_INTENT_BOUNDS.idempotencyKeyMaxBytes,
)
) {
return false;
}
for (const character of value) {
const codePoint = character.codePointAt(0) ?? 0;
if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) {
return false;
}
}
return true;
return (
validBoundedString(value, MUTATION_INTENT_BOUNDS.idempotencyKeyMaxBytes) &&
IDEMPOTENCY_KEY.test(value)
);
}
export function defineIdempotencyKey(value: unknown): string {
+11
View File
@@ -0,0 +1,11 @@
/**
* R-7.5. The one operationId grammar: the V3 contract composition admits ids
* with it, and telemetry and diagnostics validate `operation_id` with it, so
* an id the composition accepts is never dropped at the observability
* boundary. The REST v2 and browser RPC registry grammars are subsets.
*/
const OPERATION_ID = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
export function isOperationId(value: unknown): value is string {
return typeof value === "string" && OPERATION_ID.test(value);
}
+13 -3
View File
@@ -32,9 +32,19 @@ export function isValidReleaseManifestUrl(value: string): boolean {
return false;
}
if (/%2f|%5c/i.test(value)) return false;
return !value
.split("/")
.some((segment) => segment === "." || segment === "..");
if (value.split("/").some((segment) => segment === "." || segment === "..")) {
return false;
}
// R-7.3. The URL parser strips tab/CR/LF and resolves `%2e` dot segments, so
// "/\t/evil.example/m.json" becomes a cross-origin URL. The path must
// resolve to exactly itself on the page's origin.
const base = "https://release-manifest.invalid";
try {
const resolved = new URL(value, base);
return resolved.origin === base && resolved.pathname === value;
} catch {
return false;
}
}
export const capabilityOverrideArtifactSchema = z
+18
View File
@@ -97,6 +97,13 @@ export interface StaticAssetManifestV1 {
}>[];
}
/**
* Vite's content-hashed file name (`name-<hash>.ext`). Only these are
* immutable: the build generator lists nothing else, and the worker answers
* from a previous release cache only for these (D-7).
*/
export const HASHED_STATIC_ASSET_NAME = /-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/;
/** §18.2. `ca-static-v1-<first 16 lower-hex of staticAssetSetDigest>`. */
export const STATIC_CACHE_PREFIX = "ca-static-v1-" as const;
@@ -149,4 +156,15 @@ export interface ServiceWorkerRuntimeHost {
requestActivation(): Promise<ServiceWorkerActivationOutcome>;
resetOwnedCaches(): Promise<ServiceWorkerResetOutcome>;
stop(): Promise<void>;
/**
* R-6.3. A new worker was activated (by any tab), so this page runs under a
* worker of another build and should reload. Every tab is told, including
* the one that asked. Returns the unsubscribe function.
*/
onReloadRequired?(listener: () => void): () => void;
/**
* R-6.3. An update finished installing and waits for `requestActivation()`.
* Returns the unsubscribe function.
*/
onUpdateWaiting?(listener: () => void): () => void;
}
+13
View File
@@ -45,6 +45,19 @@ export const STORAGE_REGISTRY = Object.freeze({
migration: "discard",
quotaFallback: "memory",
}),
/** The chosen UI locale. Presentation normalizes whatever it reads back. */
LOCALE: defineStorageKey({
logicalName: "LOCALE",
scope: "preference",
name: "locale",
backend: "localStorage",
classification: "public-preference",
schemaVersion: 1,
valueCodec: "opaque-string-v1",
ttl: null,
migration: "discard",
quotaFallback: "memory",
}),
CHUNK_RELOAD_GUARD: defineStorageKey({
logicalName: "CHUNK_RELOAD_GUARD",
scope: "release",
+6 -2
View File
@@ -1,3 +1,6 @@
import { isHttpStatusGroup } from "./diagnostics.ts";
import { isOperationId } from "./operation-id.ts";
export const TELEMETRY_ATTRIBUTE_ALLOWLIST = Object.freeze([
"app_version",
"build_id",
@@ -108,9 +111,10 @@ const ATTRIBUTE_VALUE_POLICIES: Readonly<
Record<string, (value: string) => boolean>
> = Object.freeze({
route_id: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
operation_id: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
// R-7.5. Shared with the V3 composition and diagnostics.
operation_id: isOperationId,
error_kind: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
http_status_group: (value) => /^(?:[1-5]xx|none)$/.test(value),
http_status_group: isHttpStatusGroup,
attempt_count_bucket: (value) => /^(?:1|2|3|3-4|5\+)$/.test(value),
duration_bucket: (value) =>
/^(?:lt100ms|100-499ms|500-1999ms|gte2000ms|unknown)$/.test(
@@ -3,9 +3,10 @@
*
* During a rolling release a browser can hold HTML from one release while a
* replica answers config/manifest from another. One fresh navigation usually
* lands on a coherent tuple, so exactly one automatic reload is allowed per
* stable mismatch key. A second occurrence of the same key shows the failure;
* it never reloads again, so a persistently mixed deployment cannot loop.
* lands on a coherent tuple, so at most one automatic reload is allowed per
* session within `ttlMs`, whatever the mismatch key. Any further mismatch in
* that window shows the failure, so a persistently mixed deployment cannot
* loop even when a load balancer alternates replicas (and so the key).
*
* The marker is a single bounded value. It clears after a coherent boot and
* expires after `ttlMs`, so an old marker cannot suppress recovery forever.
@@ -56,7 +57,8 @@ export function createReleaseMismatchRecovery(
if (!store) return "show-failure";
const previous = read();
const current = now();
if (previous && previous.key === key && current - previous.at < ttlMs) {
// Key-independent: alternating replicas change the key on every boot.
if (previous && current - previous.at < ttlMs) {
return "show-failure";
}
store.write(`${key}@${current}`);
+54 -8
View File
@@ -40,15 +40,60 @@ const SECRET_KEY_FRAGMENTS = Object.freeze([
"session",
"privatekey",
"signature",
"passcode",
"passphrase",
]);
/**
* Short secret words, matched only as a whole key token (`pin`, `userPin`,
* `pin_code`, `PINCode`) so innocent keys like `spinner` or `author` survive.
*/
const SECRET_KEY_TOKENS: ReadonlySet<string> = new Set(["pwd", "pass", "auth", "otp", "pin"]);
function keyTokens(key: string): string[] {
return key
.replace(/([a-z0-9])([A-Z])/gu, "$1 $2")
.replace(/([A-Z])([A-Z][a-z])/gu, "$1 $2")
.toLowerCase()
.split(/[^a-z0-9]+/u);
}
export function isSecretTelemetryKey(key: string): boolean {
const normalized = key.toLowerCase().replace(/[^a-z0-9]/gu, "");
return SECRET_KEY_FRAGMENTS.some((fragment) => normalized.includes(fragment));
return (
SECRET_KEY_FRAGMENTS.some((fragment) => normalized.includes(fragment)) ||
keyTokens(key).some((token) => SECRET_KEY_TOKENS.has(token))
);
}
/** Values that look like bearer credentials are redacted wherever they occur. */
const SECRET_VALUE = /^(?:bearer|basic)\s+\S+|^eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\./iu;
/**
* Credential-shaped substrings are masked wherever they occur in a string:
* bearer/basic credentials, JWTs (also one cut short) and email addresses.
*/
const SECRET_VALUES: readonly RegExp[] = [
/\b(?:bearer|basic)\s+\S+/giu,
/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_.-]*/gu,
/[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/gu,
];
/** A URL query or fragment parameter: `?name=value`, `&name=value`, `#name=value`. */
const URL_PARAMETER = /([?&#])([^=&#?\s]+)=([^&#\s]+)/gu;
/** Secret URL parameter names too generic to deny as payload keys. */
const SECRET_URL_PARAMETERS: ReadonlySet<string> = new Set(["code", "key", "sig"]);
/** An email address cut by truncation, left at the very end of the string. */
const CUT_EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]*$/u;
function redactString(value: string): string {
let text = value.replace(URL_PARAMETER, (match, separator: string, name: string) =>
isSecretTelemetryKey(name) || SECRET_URL_PARAMETERS.has(name.toLowerCase())
? `${separator}${name}=${REDACTED}`
: match,
);
for (const pattern of SECRET_VALUES) text = text.replace(pattern, REDACTED);
return text;
}
function readOwnData(
source: object,
@@ -61,11 +106,12 @@ function readOwnData(
function sanitizeLeaf(value: unknown, budget: TelemetryPayloadBudget): unknown {
switch (typeof value) {
case "string":
if (SECRET_VALUE.test(value)) return REDACTED;
return value.length > budget.maxStringLength
? `${value.slice(0, budget.maxStringLength)}${TRUNCATED}`
: value;
case "string": {
if (value.length <= budget.maxStringLength) return redactString(value);
// Truncate first so the patterns only ever scan a bounded string.
const head = value.slice(0, budget.maxStringLength).replace(CUT_EMAIL, REDACTED);
return `${redactString(head)}${TRUNCATED}`;
}
case "number":
return Number.isFinite(value) ? value : null;
case "boolean":
+8 -2
View File
@@ -43,9 +43,14 @@ export function estimateTelemetryBytes(event: TelemetryEvent<unknown>): number {
}
export function createTelemetryBuffer(
options: Readonly<{ maxEvents: number; maxBytes: number }>,
options: Readonly<{
maxEvents: number;
maxBytes: number;
/** Called for each buffered event evicted to make room for a more important one. */
onEvict?: (entry: BufferedTelemetryEvent) => void;
}>,
): TelemetryBuffer {
const { maxEvents, maxBytes } = options;
const { maxEvents, maxBytes, onEvict } = options;
if (!Number.isSafeInteger(maxEvents) || maxEvents < 1) {
throw new TypeError(`telemetry buffer maxEvents must be positive: ${maxEvents}`);
}
@@ -101,6 +106,7 @@ export function createTelemetryBuffer(
entries.splice(victim, 1);
bytes -= victimEntry.bytes;
dropped += 1;
onEvict?.(victimEntry);
}
entries.push(
Object.freeze(
@@ -57,6 +57,11 @@ export class TelemetryDeduplicator {
return this.#entries.get(fingerprint)?.count ?? 0;
}
/** Forgets a fingerprint whose event was never delivered, so it is admitted again. */
forget(fingerprint: string): void {
this.#entries.delete(fingerprint);
}
#evict(now: number): void {
if (this.#entries.size < this.maxEntries) return;
for (const [fingerprint, entry] of this.#entries) {
+75 -11
View File
@@ -25,11 +25,15 @@ import { createDeterministicSampler } from "./telemetry-sampler.ts";
*
* Every stage has an explicit ceiling, and no stage can throw or reject into
* the business caller: internal failures become dropped-event counters.
*
* A duplicate inside the dedup window is not sent on its own. Its count is held
* per fingerprint and delivered as `occurrences` on the next flush, or on a
* flush when the dedup window closes, whichever comes first (D-6).
*/
export type TelemetryBatchItem = Readonly<{
event: TelemetryEvent<unknown>;
fingerprint: string;
/** Occurrences collapsed into this fingerprint in the current window. */
/** Occurrences of this fingerprint not reported by an earlier item. */
occurrences: number;
}>;
@@ -125,13 +129,22 @@ export function createTelemetryPipeline(
const buffer = createTelemetryBuffer({
maxEvents: budget.maxBufferedEvents,
maxBytes: budget.maxBufferedBytes,
// An evicted event was never delivered; it must not keep suppressing.
onEvict: (entry) => {
if (entry.fingerprint !== undefined) dedup.forget(entry.fingerprint);
},
});
/** Duplicates counted but not yet reported, per fingerprint. */
const held = new Map<string, { event: TelemetryEvent<unknown>; count: number }>();
/** Send timestamps inside the current rate window; never above the limit. */
const sendTimes: number[] = [];
let disposed = false;
let flushScheduled = false;
let rateTimer: unknown = null;
let windowTimer: unknown = null;
/** An explicit flush or a closed dedup window asks for held counts. */
let heldDue = false;
let activeFlush: Promise<void> | null = null;
const counters = {
accepted: 0,
@@ -168,20 +181,58 @@ export function createTelemetryPipeline(
});
}
function hold(event: TelemetryEvent<unknown>, fingerprint: string): void {
const entry = held.get(fingerprint);
if (entry) {
entry.count += 1;
return;
}
// Bounded like the dedup table; past it a duplicate is only counted in stats.
if (held.size >= budget.maxFingerprints) return;
held.set(fingerprint, { event, count: 1 });
if (windowTimer !== null || disposed) return;
windowTimer = setTimer(() => {
windowTimer = null;
void flushHeld();
}, budget.dedupWindowMs);
}
/**
* Held counts ride along with buffered events for free. They get a batch of
* their own only when due, so a duplicate never triggers a send by itself.
*/
function pending(): boolean {
return buffer.size > 0 || (heldDue && held.size > 0);
}
function takeBatch(): TelemetryBatchItem[] {
const batch: TelemetryBatchItem[] = buffer.take(budget.maxBatchEvents).map((entry) => {
const fingerprint = entry.fingerprint ?? "";
const duplicates = held.get(fingerprint)?.count ?? 0;
held.delete(fingerprint);
return Object.freeze({ event: entry.event, fingerprint, occurrences: 1 + duplicates });
});
for (const [fingerprint, entry] of held) {
if (batch.length >= budget.maxBatchEvents) break;
held.delete(fingerprint);
batch.push(Object.freeze({ event: entry.event, fingerprint, occurrences: entry.count }));
}
if (held.size === 0) {
heldDue = false;
if (windowTimer !== null) clearTimer(windowTimer);
windowTimer = null;
}
return batch;
}
async function drain(): Promise<void> {
while (!disposed && buffer.size > 0) {
while (!disposed && pending()) {
const at = now();
if (!rateAllows(at)) {
armRateTimer(at);
return;
}
const batch = buffer.take(budget.maxBatchEvents).map((entry) =>
Object.freeze({
event: entry.event,
fingerprint: entry.fingerprint ?? "",
occurrences: Math.max(1, dedup.count(entry.fingerprint ?? "")),
}),
);
const batch = takeBatch();
sendTimes.push(at);
counters.sends += 1;
try {
@@ -195,7 +246,7 @@ export function createTelemetryPipeline(
function flush(): Promise<void> {
if (activeFlush) return activeFlush;
if (disposed || buffer.size === 0) return Promise.resolve();
if (disposed || !pending()) return Promise.resolve();
activeFlush = drain()
.catch(() => undefined)
.finally(() => {
@@ -204,6 +255,11 @@ export function createTelemetryPipeline(
return activeFlush;
}
function flushHeld(): Promise<void> {
heldDue = held.size > 0;
return flush();
}
function admit(event: TelemetryEvent<unknown>): void {
if (disposed) return;
if (!isTelemetryEnvelopeValid(event)) {
@@ -228,6 +284,7 @@ export function createTelemetryPipeline(
const fingerprint = fingerprintTelemetryEvent(redacted);
if (!dedup.record(fingerprint, now())) {
counters.deduplicated += 1;
hold(redacted, fingerprint);
return;
}
// 4. sample (deterministic by interaction; severe events always kept)
@@ -236,12 +293,16 @@ export function createTelemetryPipeline(
!sampler.keep(redacted.interactionId ?? fingerprint)
) {
counters.sampledOut += 1;
// Its duplicates must not be reported as held occurrences.
dedup.forget(fingerprint);
return;
}
// 5. buffer
if (buffer.push(redacted, estimateTelemetryBytes(redacted), fingerprint)) {
counters.accepted += 1;
counters.peakBuffered = Math.max(counters.peakBuffered, buffer.size);
} else {
dedup.forget(fingerprint);
}
// 6-8. rate limit, batch and transport happen on flush.
scheduleFlush();
@@ -256,7 +317,7 @@ export function createTelemetryPipeline(
}
return Promise.resolve();
},
flush,
flush: flushHeld,
stats(): TelemetryPipelineStats {
return Object.freeze({
accepted: counters.accepted,
@@ -277,7 +338,10 @@ export function createTelemetryPipeline(
disposed = true;
if (rateTimer !== null) clearTimer(rateTimer);
rateTimer = null;
if (windowTimer !== null) clearTimer(windowTimer);
windowTimer = null;
buffer.clear();
held.clear();
},
});
}
@@ -177,7 +177,9 @@ export function useApplicationQuery<Value>(
data: query.data,
state: deriveAsyncState({
data: query.data,
isInitialLoading: query.isPending,
// A disabled query is pending but idle; a paused offline first load is
// pending and still waiting, which `isLoading` would miss.
isInitialLoading: query.isPending && query.fetchStatus !== "idle",
failure:
!hasData && query.error instanceof ApplicationQueryError
? query.error.failure
@@ -3,6 +3,7 @@ import {
type ErrorInfo,
type ReactNode,
} from "react";
import { Button } from "../design-system/index.ts";
import { useLocale } from "../i18n/index.ts";
type RecoveryResult =
@@ -31,7 +32,11 @@ export function isChunkLoadFailure(error: unknown): boolean {
value.includes("chunkloaderror") ||
value.includes("loading chunk") ||
value.includes("dynamically imported module") ||
value.includes("failed to fetch module script")
value.includes("failed to fetch module script") ||
// WebKit's wording for the same failed dynamic import.
value.includes("importing a module script failed") ||
// Vite rethrows a `vite:preloadError` into the import unless prevented.
value.includes("unable to preload css")
);
}
@@ -110,6 +115,10 @@ function ChunkRecoverySurface({
<section className="ui-page" role="alert" data-recovery-reason={reason}>
<h1>{message("chunk.failure.title")}</h1>
<p>{message("chunk.failure.description")}</p>
{/* The automatic reload-once already declined; this one is the user's. */}
<Button onClick={() => window.location.reload()}>
{message("action.reloadOnce")}
</Button>
</section>
);
}
@@ -378,9 +378,17 @@ export const Dialog = forwardRef<HTMLDialogElement, DialogProps>(
const previousFocus = previousFocusRef.current;
previousFocusRef.current = null;
const restoreFocus = () => {
// Restore only focus the dialog still owns. If something else (a
// route change) already placed focus outside it, do not steal it.
const active = document.activeElement;
const focusIsUnclaimed =
active === null ||
active === document.body ||
dialog.contains(active);
if (
focusRestoreGenerationRef.current === generation &&
previousFocus?.isConnected
previousFocus?.isConnected &&
focusIsUnclaimed
) {
previousFocus.focus();
}
+8 -2
View File
@@ -74,9 +74,12 @@ const LocaleContext = createContext<LocaleContextValue>(DEFAULT_CONTEXT);
export function LocaleProvider({
children,
initialLocale = "ko-KR",
onLocaleChange,
}: Readonly<{
children: React.ReactNode;
initialLocale?: SupportedLocale;
/** Persists a user's choice; the provider itself stays storage-free. */
onLocaleChange?: (locale: SupportedLocale) => void;
}>) {
const [locale, setLocaleState] = useState<SupportedLocale>(() =>
normalizeLocale(initialLocale),
@@ -92,7 +95,10 @@ export function LocaleProvider({
() => ({
locale,
direction,
setLocale: setLocaleState,
setLocale(next) {
setLocaleState(next);
onLocaleChange?.(next);
},
message: (key, ...args) => formatMessage(locale, key, ...args),
resolve: (key) => resolveMessage(locale, key),
date: (dateValue, options) => formatDate(locale, dateValue, options),
@@ -105,7 +111,7 @@ export function LocaleProvider({
selectPlural(locale, pluralValue, choices),
select: (selectValue, choices) => selectMessage(selectValue, choices),
}),
[direction, locale],
[direction, locale, onLocaleChange],
);
return (
+11 -2
View File
@@ -157,7 +157,12 @@ export function AppShell() {
returnFocusRef={navigationTriggerRef}
title={message("shell.menu")}
>
<PrimaryNavigation id="mobile-primary-navigation" />
{/* Close before the route commits: while the modal is open the page
is inert and the new route cannot take focus. */}
<PrimaryNavigation
id="mobile-primary-navigation"
onNavigate={() => setNavigationOpen(false)}
/>
</Drawer>
<main className="app-shell__content" id="main-content" tabIndex={-1}>
<Outlet />
@@ -166,7 +171,10 @@ export function AppShell() {
);
}
function PrimaryNavigation({ id }: Readonly<{ id: string }>) {
function PrimaryNavigation({
id,
onNavigate,
}: Readonly<{ id: string; onNavigate?: () => void }>) {
const { resolve, message } = useLocale();
const runtime = useApplicationRuntime();
// §3.5. A feature the runtime document disabled does not advertise itself.
@@ -185,6 +193,7 @@ function PrimaryNavigation({ id }: Readonly<{ id: string }>) {
`app-navigation__link${isActive ? " is-active" : ""}`
}
end={definition.path === "/"}
onClick={onNavigate}
to={definition.path}
>
{resolve(`route.${definition.routeId}.navigation`)}
@@ -0,0 +1,23 @@
import type { ReactNode } from "react";
import { LocaleProvider, normalizeLocale } from "../i18n/index.ts";
import { useApplicationPreferences } from "./application-provider.tsx";
import { ThemeProvider } from "./theme-provider.tsx";
/**
* User preferences outlive a session. Mount this above the server-state scope
* fence so a session change (FENCED → READY) does not reset locale or theme.
*/
export function PreferenceProviders({
children,
}: Readonly<{ children: ReactNode }>) {
const preferences = useApplicationPreferences();
return (
<LocaleProvider
initialLocale={normalizeLocale(preferences.getLocale() ?? "ko-KR")}
onLocaleChange={preferences.setLocale}
>
<ThemeProvider>{children}</ThemeProvider>
</LocaleProvider>
);
}
+101 -42
View File
@@ -3,7 +3,6 @@ import {
type ReactNode,
Suspense,
useEffect,
useMemo,
useRef,
useState,
} from "react";
@@ -21,6 +20,7 @@ import {
import {
getRoute,
ROUTE_FEATURE_OWNER,
ROUTE_REGISTRY,
} from "../../features/installed-feature-contracts.ts";
import {
PLATFORM_ROUTE_REGISTRY,
@@ -35,11 +35,14 @@ import {
FeatureBoundary,
RouteBoundary,
} from "../boundaries/render-error-boundary.tsx";
import { ChunkRecoveryBoundary } from "../boundaries/chunk-recovery-boundary.tsx";
import {
ChunkRecoveryBoundary,
isChunkLoadFailure,
} from "../boundaries/chunk-recovery-boundary.tsx";
import { ContextErrorBoundary } from "../../platform/errors/context-error-boundary.tsx";
import { FeatureErrorBoundary } from "../../platform/errors/feature-error-boundary.tsx";
import { Button, PageHeader } from "../design-system/index.ts";
import { LocaleProvider, useLocale } from "../i18n/index.ts";
import { useLocale } from "../i18n/index.ts";
import { AppShell } from "../layouts/app-shell.tsx";
import {
useApplicationDiagnostics,
@@ -47,7 +50,6 @@ import {
useApplicationRuntime,
} from "../providers/application-provider.tsx";
import { SessionProvider, useSession } from "../providers/session-provider.tsx";
import { ThemeProvider } from "../providers/theme-provider.tsx";
import {
createRedirectLoopGuard,
decideRouteAccess,
@@ -139,14 +141,17 @@ function RouteLifecycle({
definition: RouteDefinition;
buildId: string;
}) {
const location = useLocation();
const { pathname, search } = useLocation();
const { message, resolve } = useLocale();
const diagnostics = useApplicationDiagnostics();
// A locale change re-renders the title only; it is not a route change.
useEffect(() => {
document.title = message("route.documentTitle", {
title: resolve(`route.${definition.routeId}.title`),
appName: message("common.appName"),
});
}, [definition, message, resolve]);
useEffect(() => {
const main = document.getElementById("main-content");
main?.focus({ preventScroll: true });
try {
@@ -160,15 +165,7 @@ function RouteLifecycle({
routeId: definition.routeId,
buildId,
});
}, [
buildId,
definition,
diagnostics,
location.key,
location.pathname,
message,
resolve,
]);
}, [buildId, definition, diagnostics, pathname, search]);
return null;
}
@@ -278,17 +275,35 @@ type ExecutableRouteRuntime = Readonly<{
Component: ElementType;
}>;
function RegisteredRoute({
routeId,
buildId,
runtimeOverride,
paramsOverride,
}: {
type RegisteredRouteProps = {
routeId: RouteId;
buildId: string;
runtimeOverride?: ExecutableRouteRuntime;
paramsOverride?: Readonly<Record<string, string | undefined>>;
}) {
};
/**
* Title, focus and route telemetry belong to every answer a route gives,
* including auth-required, invalid-address and disabled-feature surfaces.
*/
function RegisteredRoute(props: RegisteredRouteProps) {
return (
<>
<RouteLifecycle
definition={getRoute(props.routeId)}
buildId={props.buildId}
/>
<RouteSurface {...props} />
</>
);
}
function RouteSurface({
routeId,
buildId,
runtimeOverride,
paramsOverride,
}: RegisteredRouteProps) {
const definition = getRoute(routeId);
const routerParams = useParams();
const params = paramsOverride ?? routerParams;
@@ -316,9 +331,11 @@ function RegisteredRoute({
const content = (
<RouteInputProvider input={parsed.data}>
<CanonicalRouteRedirect input={parsed.data} />
<RouteLifecycle definition={definition} buildId={buildId} />
<Suspense fallback={<RouteLoadingSurface definition={definition} />}>
{/* React Router reuses this instance across sibling routes; the key
keeps one route's failed chunk from latching onto the next. */}
<ChunkRecoveryBoundary
key={definition.routeId}
chunkId={definition.chunkId}
recover={recovery.recoverChunk}
>
@@ -366,25 +383,42 @@ function isContextRouteHandle(value: unknown): value is ContextRouteHandle {
);
}
/** The registered route a URL names, to key chunk recovery on its chunk. */
function routeChunkId(pathname: string): string | undefined {
const routes = Object.values(ROUTE_REGISTRY).map((definition) => ({
id: definition.routeId,
path: definition.path,
}));
const routeId = matchRoutes(routes, pathname)?.at(-1)?.route.id;
return routeId === undefined ? undefined : getRoute(routeId).chunkId;
}
function Rethrow({ error }: Readonly<{ error: unknown }>): never {
throw error;
}
function ContextRouteGateway({
routeModule,
buildId,
}: Readonly<{ routeModule: ContextRouteModule; buildId: string }>) {
const location = useLocation();
const { message } = useLocale();
const recovery = useApplicationRecovery();
const [routes, setRoutes] = useState<readonly RouteObject[] | null>(null);
const [failed, setFailed] = useState(false);
const [failure, setFailure] = useState<Readonly<{ error: unknown }> | null>(
null,
);
useEffect(() => {
let active = true;
setRoutes(null);
setFailed(false);
setFailure(null);
void routeModule.loadRoutes().then(
(loaded) => {
if (active) setRoutes(loaded);
},
() => {
if (active) setFailed(true);
(error: unknown) => {
if (active) setFailure({ error });
},
);
return () => {
@@ -403,7 +437,20 @@ function ContextRouteGateway({
</ContextErrorBoundary>
);
if (failed) return <RouteFailureSurface />;
if (failure) {
// A routes module that failed to download after a deploy gets the same
// reload-once recovery as a route page chunk.
return isChunkLoadFailure(failure.error) ? (
<ChunkRecoveryBoundary
chunkId={routeChunkId(location.pathname) ?? routeModule.id}
recover={recovery.recoverChunk}
>
<Rethrow error={failure.error} />
</ChunkRecoveryBoundary>
) : (
<RouteFailureSurface />
);
}
if (routes === null) {
return (
<section className="ui-page route-loading" aria-live="polite" aria-busy="true">
@@ -467,7 +514,13 @@ function createRegisteredRoutes(buildId: string): RouteObject[] {
id: `CONTEXT:${routeModule.id}`,
path: routeModule.path,
element: (
<ContextRouteGateway routeModule={routeModule} buildId={buildId} />
// Keyed: React Router reuses the instance across sibling contexts,
// and the previous context's routes must never match the new URL.
<ContextRouteGateway
key={routeModule.id}
routeModule={routeModule}
buildId={buildId}
/>
),
}),
);
@@ -482,24 +535,30 @@ function createRegisteredRoutes(buildId: string): RouteObject[] {
];
}
/**
* Locale and theme come from `PreferenceProviders` above this component, which
* the server-state scope fence may remount on a session change.
*/
export function AppRouter({
basename = "/",
buildId = "local-build",
}: Readonly<{ basename?: string; buildId?: string }>) {
const router = useMemo(
() =>
createBrowserRouter(createRegisteredRoutes(buildId), {
basename,
}),
[basename, buildId],
);
const [router, setRouter] = useState<ReturnType<
typeof createBrowserRouter
> | null>(null);
// Created in the effect that disposes it: a disposed router never listens
// to history again, so StrictMode's replayed mount needs a fresh one, and a
// remount must not leave the old router's popstate listener behind.
useEffect(() => {
const created = createBrowserRouter(createRegisteredRoutes(buildId), {
basename,
});
setRouter(created);
return () => created.dispose();
}, [basename, buildId]);
return (
<LocaleProvider>
<ThemeProvider>
<SessionProvider>
<RouterProvider router={router} />
</SessionProvider>
</ThemeProvider>
</LocaleProvider>
<SessionProvider>
{router ? <RouterProvider router={router} /> : null}
</SessionProvider>
);
}
+112
View File
@@ -0,0 +1,112 @@
# Implementation Plan: src 리뷰 긴급·필수 항목 수정
## Overview
`SPEC.md`의 요구사항 47개(R-0 + R-1.1 ~ R-9.3)를 작업 50개로 나눠 고친다. R-3.2, R-6.3, R-8.3은 각각 두 작업으로 쪼갰다. 작업마다 실패하는 테스트를 먼저 쓰고, 고치고, 전체 게이트를 돌리고, 커밋 하나를 만든다. 작업 목록과 완료 조건은 `tasks/todo.md`에 있다.
- 브랜치: `fix/src-review-2026-09-24`
- 기준 커밋: `b04d570`
## Architecture Decisions
- 결정 D-1 ~ D-7은 `SPEC.md` "결정" 표를 따른다.
- 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
- 공개 포트는 추가만 한다. 기존 시그니처는 깨지 않는다.
- 버그를 정상 동작으로 고정한 기존 테스트는 같은 커밋에서 고친다. 해당 테스트: `tests/unit/legacy-and-optional-network-remediation.test.ts:136`, `tests/unit/release-mismatch-recovery.test.ts:64` 부근, `tests/platform/telemetry/telemetry-pipeline.test.ts:93`.
## 실행 방식
1. **Phase 0 (순차):** T01(R-0)을 먼저 끝낸다. 이게 끝나야 모든 작업에서 게이트를 돌릴 수 있다.
2. **Phase 1 (병렬 레인 9개):** 영역별 레인을 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은 `fix/src-review-2026-09-24` HEAD(T01 반영 후)에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 RED → GREEN → 게이트 → 커밋한다.
3. **통합 (순차):** 레인 브랜치를 하나씩 `fix/src-review-2026-09-24`에 rebase·병합한다. 레인마다 병합한 뒤 전체 게이트를 돌린다(체크포인트).
4. **최종 체크포인트:** 전체 게이트, `build`, 깨끗한 체크아웃 재현(`src/.generated` 삭제 후 게이트)을 확인한다.
| 레인 | 영역 | 작업 |
|---|---|---|
| A | browser-transfer | T02–T05 |
| B | browser-files / cache / cross-context | T06–T10 |
| C | http / query-cache / auth | T11–T16 |
| D | realtime | T17–T20 |
| E | storage | T21–T25 |
| F | service-worker / web-push | T26–T33 |
| G | contracts | T34–T38 |
| H | presentation | T39–T47 |
| I | bootstrap / platform | T48–T50 |
레인끼리는 파일이 거의 겹치지 않는다. 겹칠 수 있는 곳은 `docs/reviews/adapters/INVENTORY.md`(adapter 파일 추가 시)와 `src/bootstrap/`(H의 T45와 I)이다. 통합 단계에서 해결한다.
## Task List (요약 — 상세는 tasks/todo.md)
### Phase 0: 기반
- [x] T01 R-0 깨끗한 체크아웃에서 게이트 동작
### Checkpoint 0
- [x] `src/.generated` 삭제 후 arch/types/lint/unit/component/verify:documentation 통과
### Phase 1: 레인 A–I (병렬)
- [x] 레인 A: T02–T05
- [x] 레인 B: T06–T10
- [x] 레인 C: T11–T16 (고위험 T12, T13, T15 포함)
- [x] 레인 D: T17–T20
- [x] 레인 E: T21–T25 (고위험 T21, T22, T24, T25 포함)
- [x] 레인 F: T26–T33 (고위험 T33 포함)
- [x] 레인 G: T34–T38 (고위험 T37 포함)
- [x] 레인 H: T39–T47
- [x] 레인 I: T48–T50 (고위험 T50 포함)
### Checkpoint 레인별 (통합할 때마다)
- [x] check:architecture, check:types:app, check:types:test, lint, test:unit, test:component 통과
- [x] adapter 파일을 바꿨으면 check:adapter-inventory 통과
### Checkpoint 최종
- [x] 위 게이트 + `corepack pnpm build` 통과
- [x] 깨끗한 체크아웃 재현 통과
- [x] 리뷰 문서의 해당 항목 47개에 해결 커밋을 대응(todo 체크)
## 고위험 작업 (계획 승인 = 이 작업들의 사전 승인)
| 작업 | 이유 | 안전장치 |
|---|---|---|
| T12, T13 (R-3.2) | 세션·캐시 fence 동작이 바뀜 | 상태가 실제로 바뀌면 여전히 fence됨을 테스트로 고정 |
| T15 (R-3.4) | 자격증명 헤더 검증 | 기존 정상 토큰 통과 테스트 유지 |
| T21, T22, T24 (R-5.1, R-5.2, R-5.4) | 삭제 경로 | 참조 중 청크와 다른 파티션 행은 절대 지우지 않음을 테스트로 고정 |
| T25 (R-5.5) | 저장 데이터 판독 규칙 | 기존 manifest 객체가 정책 변경 뒤에도 읽힘을 테스트로 고정 |
| T33 (R-6.7) | 푸시 동의 | 크래시 복구(local ACTIVE) 재등록은 유지됨을 테스트로 고정 |
| T37 (R-7.4) | CSRF 규칙 강화 | 설치된 기존 operation이 모두 통과함을 확인 |
| T50 (R-9.3) | 리댁션 | 정상 텔레메트리 값(enum, id)이 가려지지 않음을 테스트로 고정 |
모두 코드 변경이라 `git revert`로 되돌릴 수 있다. 배포, 데이터 마이그레이션, 비밀값 변경은 없다.
## Risks and Mitigations
| Risk | Impact | Mitigation |
|---|---|---|
| worktree마다 `node_modules`가 없음 | Med | 레인 시작 시 `corepack pnpm install --frozen-lockfile --prefer-offline` |
| 레인 9개가 동시에 테스트를 돌려 느려짐 | Low | 레인 안에서는 관련 테스트만, 커밋 전에만 전체 unit/component |
| INVENTORY.md 병합 충돌 | Low | 통합 단계에서 수동 병합 후 `check:adapter-inventory` |
| 브라우저에서만 재현되는 항목(T06, T09, T26, T29, T31, T32, T44) | Med | fake로 조건을 재현. 실제 브라우저 확인은 "미검증"으로 최종 보고 |
| T20 성능 요구(10배)는 CI에서 측정하기 불안정 | Low | 정확성 테스트는 자동, 성능은 벤치 스크립트 수동 측정값을 커밋 메시지에 기록 |
| R-0 방식이 pnpm pre/post 훅에 의존하면 환경마다 다름 | Med | 훅에 의존하지 않고 진입점에서 명시적으로 생성 |
## 결과 (2026-09-24)
50개 작업을 모두 커밋했다. 레인 9개를 병합할 때마다 전체 게이트를 돌렸다.
깨끗한 체크아웃(`src/.generated` 삭제) 기준 최종 게이트 결과:
- 통과: check:architecture, check:types, lint, test:runtime-schema(53), test:unit(1890), test:contract(12), test:component(149), test:integration(104), test:recipes(17), test:reference-feature(56), test:platform(245), check:release-coherence(46), check:adapter-inventory, check:registries, check:ci, verify:documentation, build
- Playwright: test:e2e는 Chromium·Firefox 전부 통과, test:browser-capabilities도 Chromium·Firefox 전부 통과. WebKit은 이 머신에 시스템 의존성이 없어 실행 자체가 안 됨(`playwright install-deps` 필요)
계획 밖에서 추가로 한 일:
- R-0 1차 수정이 진입점 36개를 놓쳤다. 여기에는 CI 게이트 실행기 `ci:gate`와 `check:ci`가 포함된다. 가드 테스트가 import를 따라가 검사하도록 바꾸고 누락분을 채웠다(`7dfb89f`).
- `check:adapter-inventory`가 기준 브랜치에서도 실패하고 있었다(6f6c48e에서 추가한 파일 2개가 인벤토리에 없음). 행을 추가했다(`2fb07c8`).
## Open Questions (사용자 결정 필요)
1. **번들 예산**: `check:optional-recipes`가 기준 커밋부터 실패하고 있었다. 기준 커밋 대비 file-transfer는 99바이트 줄었고, realtime은 초과폭이 9바이트에서 139바이트로 늘었다. offline-indexeddb는 이번 수정으로 예산을 56바이트 새로 넘었다. 예산을 올릴지, 코드를 줄일지 결정이 필요하다.
2. **T29(R-6.3b) vs T32(R-6.6)**: fetch를 manifest URL로만 가로채도록 좁혔기 때문에, 이전 캐시 fallback은 현재 manifest에 있는 URL에만 적용된다. 리뷰의 원래 시나리오(옛 빌드 lazy chunk)는 여전히 네트워크로만 간다. 가로채는 범위를 "same-origin GET + 해시 파일명"으로 넓힐지 결정이 필요하다.
3. **T12(R-3.2a)**: 기존 owner는 subject를 제공하지 않는다. 그래서 인증 상태에서 인증 상태로 오는 알림(토큰 갱신 등)은 owner가 `readSubject`를 구현하기 전까지 여전히 캐시를 비운다. fail-closed 기본값이다.
4. **T41(R-8.8)**: disabled 쿼리는 이제 `empty`("데이터가 없습니다")로 보인다. 의존 쿼리에 이 화면이 맞지 않다면 `idle` 상태를 따로 만들어야 한다.
5. **T20(R-4.4)**: 250KB 벤치에서 ASCII는 36~80배 빨라졌지만 멀티바이트 위주 입력은 약 5배에 그쳤다. 10배 목표는 ASCII만 달성했다.
6. **T14(R-3.3)**: V2 client(`client.ts`)는 바꾸지 않았다. V2에서 HTML 바디 502는 여전히 CONTENT_TYPE_MISMATCH이고 재시도하지 않는다.
실제 브라우저에서 따로 확인해야 하는 항목: SW 두 빌드 간 업데이트 순서(T26~T30), 실제 서버의 MIME·gzip 응답(T31), 네이티브 file picker 호출(T09), `Cache.match`와 Vary(T10), 멀티 탭 OPFS 경합(T22), 모바일 드로어 포커스(T44), Safari 청크 오류 메시지(T40). WebKit 계열은 전부 미검증이다.
+337
View File
@@ -0,0 +1,337 @@
# Tasks: src 리뷰 긴급·필수 항목 수정
각 작업의 문제 설명은 `docs/reviews/2026-09-24-src-full-review.md` 해당 섹션을 본다. 요구사항은 `SPEC.md`, 실행 방식은 `tasks/plan.md`에 있다.
## 모든 작업에 공통인 검증
- [x] RED: 재현 테스트가 수정 전에 실패한다
- [x] GREEN: 해당 테스트 파일 통과 — `node scripts/run-vitest.ts run <test file>`
- [x] 게이트 통과 — `corepack pnpm check:architecture && corepack pnpm check:types:app && corepack pnpm check:types:test && corepack pnpm lint && corepack pnpm test:unit && corepack pnpm test:component`
- [x] adapter 파일을 추가하거나 이동했으면 `docs/reviews/adapters/INVENTORY.md`를 갱신하고 `corepack pnpm check:adapter-inventory` 통과
- [x] 커밋 1개, 메시지에 R-ID 포함, 해당 작업 파일만 스테이징
---
## Phase 0
### T01 — R-0 깨끗한 체크아웃에서 게이트 동작 (리뷰 6.0)
- 완료 조건:
- [x] `rm -rf src/.generated` 뒤 `dev`(기동까지), `build`, `check:architecture`, `check:types:app`, `test:unit`, `test:component`, `verify:documentation`이 통과한다
- [x] CI(`config/ci/gates.json` → 생성 workflow)도 생성 단계를 거친다. `check:ci-contract` 등 관련 검사가 통과한다
- 테스트: 스크립트 레벨 검증(위 명령). 필요하면 `tests/scripts/generate-product-feature-index.test.ts`에 보강
- 파일: `package.json`, `scripts/*`(진입점), `config/ci/gates.json`, 생성 workflow
- 의존: 없음 · 크기: M
---
## 레인 A — browser-transfer
### T02 — R-1.1 dispose 재시도 가능 (6.1-1)
- 완료 조건: [x] deadline 초과 뒤 작업이 끝나면 두 번째 `dispose()`가 성공하고 `lifecycle()==="CLOSED"`, checkpoint store가 닫힌다
- 테스트: `tests/unit/resumable-upload-runtime-teardown.test.ts`
- 파일: `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts`
- 의존: T01 · 크기: S
### T03 — R-1.4 크기 초과는 LIMIT_EXCEEDED (6.1-4)
- 완료 조건: [x] `maxFileBytes`/`maxPartCount` 초과 upload가 `LIMIT_EXCEEDED`를 반환한다
- 테스트: `tests/unit/resumable-upload-runtime.test.ts`
- 파일: `resumable-upload-runtime.ts`
- 의존: T01 · 크기: S
### T04 — R-1.2 opaque ID 문법 단일화 (6.1-2)
- 완료 조건: [x] `-`/`_`로 시작하는 43자 base64url ID가 session, part 발급, download 발급까지 통과한다 [x] 정규식 정의는 한 곳
- 테스트: `tests/unit/presigned-transfer*.test.ts` 또는 `resumable-upload-*` 중 해당 파일
- 파일: `resumable-upload/checkpoint-schema.ts`, `presigned/presigned-capability-http-provider.ts`, `presigned/presigned-transfer-executor.ts`
- 의존: T01 · 크기: S
### T05 — R-1.3 동시성 정책 정합 (6.1-3, D-2)
- 완료 조건: [x] 정책 검증이 `partSize×maxConcurrency×copyFactor > maxInFlightBytes`를 거절한다 [x] 기본 정책이 검증을 통과한다 [x] createSession이 실제 worker 수를 요청한다
- 테스트: `tests/unit/resumable-upload-runtime.test.ts`(기본 정책 사용 케이스)
- 파일: `resumable-upload/runtime-policy.ts`, `resumable-upload-runtime.ts`, 필요 시 `docs/architecture/presigned-transfer-and-image-cdn.md`
- 의존: T01 · 크기: S
## 레인 B — browser-files / cache-storage / cross-context
### T06 — R-2.1 BOUNDED_OBJECT_URL open 실패 시 Result 반환 (6.2-1)
- 완료 조건: [x] presigned source + BOUNDED_OBJECT_URL에서 open 중 abort하면 `deliver()`가 `{ok:false, ABORTED}`로 resolve된다 [x] 늦게 온 lease가 닫힌다
- 테스트: `tests/unit/browser-file-download.test.ts`
- 파일: `src/adapters/browser-files/download-delivery-adapter.ts`
- 의존: T01 · 크기: S
### T07 — R-2.2 watermark를 TTL과 분리 (6.2-2)
- 완료 조건: [x] 같은 source의 seq 1 → 61초 뒤 seq 2가 `NEXT`로 전달된다 [x] watermark 메모리는 `sourceCapacity`로만 제한된다
- 테스트: `tests/unit/cross-tab-invalidation.test.ts`
- 파일: `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts`
- 의존: T01 · 크기: S
### T08 — R-2.3 발행 실패 뒤에도 수신 유지, 수신 불가면 DEGRADED (6.2-3, D-4)
- 완료 조건: [x] postMessage가 한 번 실패한 탭이 다른 탭의 broadcast를 계속 받는다 [x] BroadcastChannel을 만들 수 없는 탭의 status가 DEGRADED다
- 테스트: `tests/unit/cross-tab-invalidation.test.ts`(발행 탭은 정상, 수신 탭이 실패하는 구성)
- 파일: `browser-cross-context-invalidation.ts`, 필요 시 status 타입(`src/application/ports/…`)
- 의존: T07 · 크기: S
### T09 — R-2.4 picker 함수 bind 제거 (6.2-4)
- 완료 조건: [x] `this`가 options이면 throw하는 fake picker를 주입해도 picker와 save가 동작한다
- 테스트: `tests/unit/browser-file-picker.test.ts`, `tests/unit/browser-file-download.test.ts`
- 파일: `src/adapters/browser-files/browser-file-picker.ts`, `download-delivery-adapter.ts`
- 의존: T06 · 크기: S
### T10 — R-2.5 cache 정책의 Vary/content-type (6.2-5)
- 완료 조건: [x] 기본 정책으로 `Vary: Accept-Encoding` 응답을 stage하고 activate할 수 있다 [x] `content-type`이 없는 정책은 `assertPublicCachePolicy`가 거부한다
- 테스트: `tests/unit/public-response-cache.test.ts`
- 파일: `src/adapters/cache-storage/public-response-cache-adapter.ts`, `public-cache-policy.ts`
- 의존: T01 · 크기: S
## 레인 C — http / query-cache / auth
### T11 — R-3.1 경로 값 `.`/`..` 거부 (6.3-1)
- 완료 조건: [x] V3 bridge가 `PATH_VALUE_INVALID`, V2 request-builder가 `PATH_PARAMETER_INVALID`를 반환한다(`"."`, `".."` 각각)
- 테스트: `tests/unit/http-contract-bridge*.test.ts`(없으면 신규), V2 request-builder 테스트
- 파일: `src/adapters/http/http-contract-bridge.ts`, `src/adapters/http/request-builder.ts`
- 의존: T01 · 크기: S
### T12 — R-3.2a scope fence는 상태가 바뀔 때만 (6.3-2) [고위험]
- 완료 조건: [x] 같은 (상태, 주체) 알림은 fence·abort·cache clear를 일으키지 않는다 [x] 상태나 주체가 바뀌면 여전히 fence된다
- 테스트: server-state-scope 런타임 테스트(`tests/unit/…server-state-scope…`)
- 파일: `src/adapters/query-cache/server-state-scope-runtime.ts`
- 의존: T01 · 크기: S
### T13 — R-3.2b 요청 전 미인증과 서버 401 구분, demo 동일 값 무알림 (6.3-2) [고위험]
- 완료 조건: [x] V3 요청 전 자격증명 없음은 `onUnauthenticated`를 호출하지 않는다 [x] 서버 401은 호출한다 [x] demo `setState`는 같은 값이면 listener를 부르지 않는다
- 테스트: `tests/unit/http-execution-v3*.test.ts`, `tests/unit/runtime-adapters.test.ts` 또는 auth 어댑터 테스트
- 파일: `src/adapters/http/http-execution-v3.ts`, `src/adapters/auth/external-session-adapter.ts`, `src/bootstrap/runtime-adapters.ts`
- 의존: T12 · 크기: M
### T14 — R-3.3 5xx 비정상 바디와 요청 쪽 위반 분류 (6.3-3)
- 완료 조건: [x] HTML/빈 바디 502/503/504가 status를 담은 서버 장애(재시도 가능)로 끝난다 [x] 바인딩 결과가 `contact-support`가 아니다 [x] `FINAL_REQUEST_INVARIANT_FAILED`/`MISSING_IDEMPOTENCY_KEY`가 `ENVELOPE_MISMATCH`로 매핑되지 않는다
- 테스트: `tests/unit/http-execution-v3.test.ts`, feature-http-binding 테스트
- 파일: `http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts`
- 의존: T13 · 크기: M
### T15 — R-3.4 자격증명 헤더 ByteString 검증 (6.3-4) [고위험]
- 완료 조건: [x] NUL, 비 Latin-1, 제어문자가 든 값이 전송 전에 `CREDENTIAL_HEADER_VALUE_INVALID`가 된다(NETWORK_FAILURE 아님) [x] 대소문자만 다른 중복 헤더가 거부된다 [x] 정상 Bearer 토큰은 통과한다
- 테스트: bridge/V3 테스트, auth 어댑터 테스트
- 파일: `http-contract-bridge.ts`, `http-execution-v3.ts`, `external-session-adapter.ts`
- 의존: T14 · 크기: M
### T16 — R-3.5 매퍼 예외를 Result로 (6.3-5)
- 완료 조건: [x] `mapSuccess`/`mapProblem`이 throw하면 `MAPPING_CONTRACT_VIOLATION` Result가 반환되고 effect가 보존된다
- 테스트: feature-http-binding 테스트
- 파일: `feature-http-binding.ts`
- 의존: T14 · 크기: S
## 레인 D — realtime
### T17 — R-4.2 hint 없는 retryable 실패도 재연결 (6.4-2)
- 완료 조건: [x] WS `NETWORK_LOST`/`RESTART`, SSE 502/504(hint 없음)가 재연결된다 [x] polling도 같다 [x] `retryable:false`는 여전히 종료된다
- 테스트: `tests/unit/realtime/realtime-reconnect-coordinator.test.ts` + WS↔reconnect 연결 테스트 신규
- 파일: `src/adapters/realtime/reconnect-coordinator.ts`, `polling/bounded-poll-coordinator.ts`
- 의존: T01 · 크기: S
### T18 — R-4.1 DRAINING 중 recovery 차단 (6.4-1)
- 완료 조건: [x] quiescence를 기다리는 동안 effect가 DRAINING이 되면 recovery가 authority를 호출하지 않고 실패한다
- 테스트: `tests/unit/realtime/stream-coordinator.test.ts`
- 파일: `src/adapters/realtime/stream-coordinator.ts`
- 의존: T01 · 크기: S
### T19 — R-4.3 barrier NONE recovery는 계속 진행 (6.4-3)
- 완료 조건: [x] SNAPSHOT_ONLY + barrier NONE 스트림에서 gap → recovery 뒤 연결이 유지되고 PROTOCOL_MISMATCH가 나지 않는다
- 테스트: consumer + coordinator 실제 조합 테스트(mock 없이)
- 파일: `src/adapters/realtime/event-consumer.ts`, 필요 시 `stream-coordinator.ts`
- 의존: T18 · 크기: M
### T20 — R-4.4 SSE 파서 성능 (6.4-4)
- 완료 조건: [x] 기존 파서 테스트가 모두 통과한다(CRLF, 분할 chunk, BOM 등) [x] 250KB chunk 벤치에서 10배 이상 빨라진다(수동 측정값을 커밋 메시지에 기록)
- 테스트: `tests/unit/realtime/sse-parser*.test.ts` + 대형 chunk 정확성 케이스
- 파일: `src/adapters/realtime/sse/sse-parser.ts`
- 의존: T01 · 크기: S
## 레인 E — storage
### T21 — R-5.1 orphan 후보 커서 (6.5-1) [고위험]
- 완료 조건: [x] 참조 중 청크 150개 뒤에 있는 orphan이 reconcile로 지워진다 [x] 참조 중 청크는 지워지지 않는다
- 테스트: `tests/unit/opfs-worker-runtime.test.ts`, `tests/unit/opfs-byte-store.test.ts`
- 파일: `src/adapters/storage/opfs/opfs-worker-runtime.ts`, `opfs-worker-protocol.ts`, `opfs-worker-client.ts`, `opfs-byte-store-adapter.ts`
- 의존: T01 · 크기: M
### T22 — R-5.2 dedup 재사용 청크의 grace 보호 (6.5-2) [고위험]
- 완료 조건: [x] 같은 digest를 다시 쓰면 청크의 mtime이 갱신되어 `listOrphanCandidates`에 나오지 않는다
- 테스트: `tests/unit/opfs-worker-runtime.test.ts`
- 파일: `opfs-worker-runtime.ts`
- 의존: T21 · 크기: S
### T23 — R-5.3 lock 대기를 RPC 타임아웃에서 분리 (6.5-3, D-3)
- 완료 조건: [x] 긴 put이 lock을 잡고 있어도 뒤에 온 put/remove가 60초에 실패하지 않고 lock을 얻은 뒤 진행된다 [x] lock 대기는 정책값 상한으로 끝난다
- 테스트: 배타 lease를 쓰는 worker/client 테스트 신규
- 파일: `opfs-worker-client.ts`, `opfs-worker-runtime.ts`, `opfs-policy.ts`
- 의존: T22 · 크기: M
### T24 — R-5.4 파티션 purge가 손상 행을 넘어 끝까지 (6.5-4) [고위험]
- 완료 조건: [x] 손상 record/sidecar/budget이 섞인 파티션에서 LOGOUT/ACCOUNT_DELETION purge가 COMPLETE된다 [x] 다른 파티션의 행은 남는다 [x] 손상은 observe로 보고된다
- 테스트: `tests/unit/indexeddb-runtime.test.ts`
- 파일: `src/adapters/storage/indexeddb/indexeddb-runtime.ts`
- 의존: T01 · 크기: M
### T25 — R-5.5 prepared-object 검증 단일화 (6.5-5) [고위험]
- 완료 조건: [x] 4MiB 청크로 저장한 객체를 정책 `chunkSizeBytes=8MiB`인 런타임에서 open, reconcile할 수 있다 [x] 검증 함수 정의는 한 곳
- 테스트: `tests/unit/opfs-worker-runtime.test.ts`, `tests/unit/indexeddb-opfs-journal.test.ts`
- 파일: 신규 공용 모듈(`src/adapters/storage/opfs/…`), `opfs-worker-runtime.ts`, `indexeddb-opfs-journal.ts`, `opfs-worker-client.ts`, INVENTORY
- 의존: T23 · 크기: M
## 레인 F — service-worker / web-push
### T26 — R-6.1 확정 이후 메시지 처리 (6.6-1)
- 완료 조건: [x] ACCEPTED 도착 시 `registration.waiting===null`, `active===worker`여도 활성화가 성공한다 [x] 관련 없는 메시지(SYNC_WAKE_OBSERVED 등)가 활성화를 실패시키지 않는다
- 테스트: page-controller 테스트
- 파일: `src/adapters/service-worker/service-worker-page-controller.ts`
- 의존: T01 · 크기: S
### T27 — R-6.2 drain 짝 맞추기 수정 (6.6-2)
- 완료 조건: [x] 빌드 N 탭과 N+1 탭이 함께 있어도 활성화가 drain을 끝내고 완료된다
- 테스트: lifecycle 테스트 + page-controller 테스트
- 파일: `service-worker-lifecycle.ts`, `service-worker-page-controller.ts`
- 의존: T26 · 크기: S
### T28 — R-6.3a reloadRequired/updateWaiting 구독 (6.6-3)
- 완료 조건: [x] host 계약에 구독 API가 추가되고, 다른 탭의 `ACTIVATED_RELOAD_REQUIRED`와 주기 update의 waiting이 구독자에게 전달된다
- 테스트: page-controller 테스트
- 파일: `service-worker-page-controller.ts`, `src/contracts/service-worker.ts`, 관련 host 타입
- 의존: T27 · 크기: M
### T29 — R-6.3b previous 캐시 fallback (6.6-3, D-7)
- 완료 조건: [x] current 캐시에 없는 hashed asset을 previous 캐시에서 제공한다 [x] hashed가 아닌 URL에는 적용되지 않는다
- 테스트: lifecycle/runtime 테스트
- 파일: `service-worker-lifecycle.ts`, 필요 시 `service-worker-static-assets.ts`
- 의존: T28 · 크기: S
### T30 — R-6.4 설치 중 워커를 ACTIVE로 보고하지 않음 (6.6-4)
- 완료 조건: [x] `installing`만 있는 등록에서 `start()`가 ACTIVE가 아닌 상태를 반환한다 [x] 설치가 끝나면 올바른 상태로 수렴한다
- 테스트: page-controller 테스트(`installing` fixture 추가)
- 파일: `service-worker-page-controller.ts`
- 의존: T27 · 크기: S
### T31 — R-6.5 MIME 동의어와 content-encoding (6.6-5)
- 완료 조건: [x] `application/javascript` 응답과 `content-encoding: gzip` + 압축 크기 Content-Length 응답이 설치된다 [x] 바이트와 sha256 검증은 유지된다
- 테스트: static-assets 테스트
- 파일: `service-worker-static-assets.ts`
- 의존: T01 · 크기: S
### T32 — R-6.6 fetch 가로채기 범위 (6.6-6)
- 완료 조건: [x] navigate, 비 GET, manifest 밖 URL에서는 `respondWith`가 호출되지 않는다 [x] manifest asset은 캐시에서 제공된다
- 테스트: service-worker entry/runtime 테스트
- 파일: `service-worker-entry.ts`, 필요 시 runtime의 `manifestUrls` 노출
- 의존: T29 · 크기: S
### T33 — R-6.7 ABSENT 재등록 조건 (6.6-7) [고위험]
- 완료 조건: [x] fence REVOKED/UNASSOCIATED + native 구독 잔존 + 서버 ABSENT → 재등록하지 않고 native를 해제한다 [x] local ACTIVE(크래시 복구)면 재등록한다
- 테스트: `tests/unit/web-push-subscription-adapter.test.ts`
- 파일: `src/adapters/web-push/push-subscription-adapter.ts`
- 의존: T01 · 크기: S
## 레인 G — contracts
### T34 — R-7.1 멱등 키 문법 (6.7-1)
- 완료 조건: [x] 앞뒤 공백, 비 ASCII, 257자 키가 거부된다 [x] UUID 등 정상 키는 통과한다 [x] 기존 고정 테스트(`legacy-and-optional-network-remediation.test.ts:136`)를 고친다
- 테스트: 위 테스트 + mutation-intent 테스트
- 파일: `src/contracts/mutation-intent.ts`
- 의존: T01 · 크기: S
### T35 — R-7.2 FEATURE_OVERRIDES 키는 금지어 검사 제외 (6.7-2)
- 완료 조건: [x] `{"FEATURE_OVERRIDES":{"cookie-consent":"DISABLED"}}`로 부팅 설정 로드가 성공한다 [x] 최상위나 다른 중첩의 금지 이름은 여전히 거부된다
- 테스트: runtime-config 테스트
- 파일: `src/contracts/env.ts`
- 의존: T01 · 크기: S
### T36 — R-7.3 매니페스트 URL 검증 (6.7-3)
- 완료 조건: [x] `"/\t/evil.example/m.json"`, 개행 포함, `/a/%2e%2e/b`가 거부된다 [x] 정상 경로는 통과한다
- 테스트: `tests/runtime-schema/runtime-config.test.ts`
- 파일: `src/contracts/release-artifacts.ts`
- 의존: T01 · 크기: S
### T37 — R-7.4 REST V2 COMMAND 메서드 규칙 (6.7-4) [고위험]
- 완료 조건: [x] `{semantics:"COMMAND", method:"GET"}`와 모르는 `semantics`/`replayPolicy` 값이 거부된다 [x] 설치된 기존 operation은 모두 통과한다
- 테스트: api-operations 테스트
- 파일: `src/contracts/api-operations.ts`
- 의존: T01 · 크기: S
### T38 — R-7.5 operationId 문법 단일화 (6.7-5)
- 완료 조건: [x] `getUser` 같은 V3 operationId의 `api.request.failed` 이벤트가 검증을 통과해 드롭되지 않는다 [x] 정의는 contracts 한 곳 [x] diagnostics도 같은 규칙
- 테스트: telemetry/diagnostics 계약 테스트
- 파일: `src/contracts/telemetry.ts`, `diagnostics.ts`, `external-contract-runtime.ts`, 공용 정의 위치
- 의존: T01 · 크기: M
## 레인 H — presentation
### T39 — R-8.1 청크 복구 상태 라우트별 초기화 (6.8-1)
- 완료 조건: [x] 라우트 A에서 청크 실패 → 라우트 B로 이동하면 B가 정상 렌더된다 [x] 실패 화면에 한 번 새로고침 버튼이 있다
- 테스트: `tests/component/chunk-recovery-boundary.test.tsx` 또는 라우터 컴포넌트 테스트
- 파일: `src/presentation/routes/app-router.tsx`, `src/presentation/boundaries/chunk-recovery-boundary.tsx`
- 의존: T01 · 크기: S
### T40 — R-8.2 WebKit/Vite 청크 실패 인식 (6.8-2)
- 완료 조건: [x] 두 메시지가 `isChunkLoadFailure`에서 true다 [x] `vite:preloadError`가 복구 경로로 이어진다
- 테스트: chunk-recovery 테스트
- 파일: `chunk-recovery-boundary.tsx`, 필요 시 `src/bootstrap/main.tsx`
- 의존: T39 · 크기: S
### T41 — R-8.8 enabled:false는 로딩 아님 (6.8-8)
- 완료 조건: [x] disabled 쿼리의 `isInitialLoading`이 false다 [x] 실제 첫 로딩은 여전히 true다
- 테스트: `tests/component/application-query*.test.tsx`
- 파일: `src/presentation/adapters/query/application-query.ts`
- 의존: T01 · 크기: XS
### T42 — R-8.4 로케일 변경 시 포커스·스크롤·재보고 없음 (6.8-4)
- 완료 조건: [x] 언어를 바꾸면 제목만 갱신되고 focus, scrollTo, reportRouteChanged가 호출되지 않는다
- 테스트: 라우터 컴포넌트 테스트
- 파일: `app-router.tsx`
- 의존: T39 · 크기: S
### T43 — R-8.5 모든 분기에서 RouteLifecycle (6.8-5)
- 완료 조건: [x] 인증필요, 잘못된 주소, 비활성 기능 화면에서 title, main focus, route 텔레메트리가 동작한다
- 테스트: 라우터 컴포넌트 테스트
- 파일: `app-router.tsx`
- 의존: T42 · 크기: S
### T44 — R-8.6 드로어 이동 시 포커스 (6.8-6)
- 완료 조건: [x] 드로어 링크로 이동하면 activeElement가 새 페이지 h1 또는 main이다 [x] Escape로 닫으면 여전히 메뉴 버튼으로 돌아간다
- 테스트: app-shell 컴포넌트 테스트
- 파일: `src/presentation/layouts/app-shell.tsx`, 필요 시 `design-system/primitives/core.tsx`
- 의존: T43 · 크기: S
### T45 — R-8.3a 로케일 저장 (6.8-3, D-5)
- 완료 조건: [x] 로케일 선택이 preferences에 저장되고 새 mount 때 저장값으로 시작한다
- 테스트: `tests/component/locale-platform.test.tsx`
- 파일: `src/presentation/i18n/locale-provider.tsx`, `src/application/ports/in/application-api.ts`, `src/application/create-application.ts`, preferences 저장 경로
- 의존: T42 · 크기: M
### T46 — R-8.3b provider를 scope fence 밖으로, router dispose (6.8-3)
- 완료 조건: [x] scope가 FENCED → READY가 되어도 LocaleProvider/ThemeProvider 상태가 유지된다 [x] AppRouter unmount 시 `router.dispose()`가 호출된다
- 테스트: 컴포넌트 테스트(세션 전환)
- 파일: `app-router.tsx`, `src/presentation/adapters/query/server-state-scope-provider.tsx`, provider 조립 위치(bootstrap/runtime-application 등)
- 의존: T45 · 크기: M
### T47 — R-8.7 context 게이트웨이 key와 청크 복구 (6.8-7)
- 완료 조건: [x] context가 바뀌면 이전 routes로 매칭하지 않는다(NOT_FOUND 텔레메트리 없음) [x] routes 모듈 로드의 청크 실패가 `recoverChunk`를 거친다
- 테스트: 라우터 컴포넌트 테스트(가짜 context 2개)
- 파일: `app-router.tsx`
- 의존: T46 · 크기: S
## 레인 I — bootstrap / platform
### T48 — R-9.1 부트 reload 세션당 1회 (6.9-1)
- 완료 조건: [x] 키가 A→B→A로 바뀌어도 TTL 안에서는 두 번째부터 `show-failure`다 [x] 기존 연속 reload 기대 테스트를 고친다
- 테스트: `tests/unit/release-mismatch-recovery.test.ts`, `tests/release/mixed-replica.test.ts`
- 파일: `src/platform/release/release-mismatch-recovery.ts`
- 의존: T01 · 크기: S
### T49 — R-9.2 중복 발생 횟수 전달 (6.9-2, D-6)
- 완료 조건: [x] 기본 스케줄(queueMicrotask)에서 같은 이벤트 1000회 → 수집기가 받는 occurrences 합계가 1000이다
- 테스트: `tests/platform/telemetry/telemetry-pipeline.test.ts`(자동 flush 켠 케이스 추가, 기존 기대값 정리)
- 파일: `src/platform/telemetry/telemetry-pipeline.ts`
- 의존: T01 · 크기: M
### T50 — R-9.3 리댁션 보강 (6.9-3) [고위험]
- 완료 조건: [x] 중간의 `Authorization: Bearer …`, URL `?access_token=…`, 이메일, `pwd`/`pass`/`auth`/`otp`/`pin` 키가 가려진다 [x] 정상 enum/id 값은 가려지지 않는다
- 테스트: redact-telemetry 테스트
- 파일: `src/platform/telemetry/redact-telemetry.ts`
- 의존: T01 · 크기: S
+117
View File
@@ -0,0 +1,117 @@
// @vitest-environment jsdom
import { render, screen, waitFor, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
/**
* jsdom has no showModal/close and no modal inertness. Browsers ignore
* focus() outside an open modal dialog, which is what made the route focus
* fail while the drawer was still open; this reproduces just that.
*/
function emulateModalDialogs() {
const dialogProto = HTMLDialogElement.prototype;
// user-event redefines focus as a getter, so patch and restore descriptors.
const focusDescriptor = Object.getOwnPropertyDescriptor(
HTMLElement.prototype,
"focus",
)!;
const nativeFocus = HTMLElement.prototype.focus;
let modal: HTMLDialogElement | null = null;
Object.defineProperties(dialogProto, {
open: {
configurable: true,
get(this: HTMLDialogElement) {
return this.hasAttribute("open");
},
},
showModal: {
configurable: true,
value(this: HTMLDialogElement) {
this.setAttribute("open", "");
modal = this;
},
},
close: {
configurable: true,
value(this: HTMLDialogElement) {
this.removeAttribute("open");
if (modal === this) modal = null;
},
},
});
Object.defineProperty(HTMLElement.prototype, "focus", {
configurable: true,
value(this: HTMLElement, options?: FocusOptions) {
if (modal && !modal.contains(this)) return;
nativeFocus.call(this, options);
},
});
return () => {
for (const key of ["open", "showModal", "close"]) {
Reflect.deleteProperty(dialogProto, key);
}
Object.defineProperty(HTMLElement.prototype, "focus", focusDescriptor);
};
}
let restoreDialogs: () => void = () => {};
beforeEach(() => {
restoreDialogs = emulateModalDialogs();
});
afterEach(() => restoreDialogs());
function renderShell() {
window.history.pushState({}, "", "/");
return render(
<ApplicationProvider application={createTestApplication()}>
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>,
);
}
describe("app shell mobile navigation drawer", () => {
it("hands focus to the new page when a drawer link navigates", async () => {
const user = userEvent.setup();
renderShell();
const menuButton = await screen.findByRole("button", { name: "메뉴" });
await user.click(menuButton);
const drawer = screen.getByRole("dialog", { name: "메뉴" });
await user.click(within(drawer).getByRole("link", { name: "UI 구성요소" }));
const heading = await screen.findByRole(
"heading",
{ name: "UI 구성요소", level: 1 },
{ timeout: 5000 },
);
await waitFor(() => expect(heading).toHaveFocus());
expect(menuButton).toHaveAttribute("aria-expanded", "false");
// The drawer's deferred focus restore must not pull focus back to the
// menu button after the page took it.
await new Promise((resolve) => setTimeout(resolve, 20));
expect(heading).toHaveFocus();
});
it("still returns focus to the menu button when Escape closes the drawer", async () => {
const user = userEvent.setup();
renderShell();
const menuButton = await screen.findByRole("button", { name: "메뉴" });
await user.click(menuButton);
expect(screen.getByRole("dialog", { name: "메뉴" })).toHaveAttribute(
"open",
);
await user.keyboard("{Escape}");
await waitFor(() => expect(menuButton).toHaveFocus());
});
});
@@ -1,5 +1,6 @@
// @vitest-environment jsdom
import { onlineManager } from "@tanstack/react-query";
import { act, renderHook, waitFor } from "@testing-library/react";
import { describe, expect, it, vi } from "vitest";
@@ -109,6 +110,54 @@ describe("application query inbound bridge", () => {
expect(physicalRefetches).toBe(1);
});
it("does not report a disabled query without data as loading", async () => {
// A dependent query waiting on its prerequisite is idle, not loading.
const client = queryClient();
const execute = vi.fn(async () => ({ ok: true as const, value: ["x"] }));
const hook = renderHook(
() =>
useApplicationQuery({
queryKey: ["resource", "waiting-on-prerequisite"],
execute,
enabled: false,
}),
{ wrapper: wrapper(client) },
);
expect(hook.result.current.state.base).not.toBe("initial-loading");
expect(execute).not.toHaveBeenCalled();
});
it("still reports a real first load as loading, including a paused offline one", async () => {
const client = queryClient();
const execute = vi.fn(
() => new Promise<ApplicationResult<string[]>>(() => {}),
);
const inFlight = renderHook(
() => useApplicationQuery({ queryKey: ["resource", "first"], execute }),
{ wrapper: wrapper(client) },
);
await waitFor(() => expect(execute).toHaveBeenCalledOnce());
expect(inFlight.result.current.state.base).toBe("initial-loading");
// Offline, TanStack pauses the first fetch (isFetching=false) instead of
// running it; the user is still waiting for data.
onlineManager.setOnline(false);
try {
const paused = renderHook(
() =>
useApplicationQuery({ queryKey: ["resource", "offline"], execute }),
{ wrapper: wrapper(client) },
);
expect(client.getQueryState(["resource", "offline"])?.fetchStatus).toBe(
"paused",
);
expect(paused.result.current.state.base).toBe("initial-loading");
} finally {
onlineManager.setOnline(true);
}
});
it("projects an initial application failure into terminal state", async () => {
const client = queryClient();
const failure = createFailure("FORBIDDEN", "LIST", 0);
@@ -1,6 +1,8 @@
// @vitest-environment jsdom
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { lazy, Suspense } from "react";
import { describe, expect, it, vi } from "vitest";
import {
@@ -8,6 +10,20 @@ import {
isChunkLoadFailure,
} from "../../src/presentation/boundaries/chunk-recovery-boundary.tsx";
import { FeatureBoundary } from "../../src/presentation/boundaries/render-error-boundary.tsx";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
// The states page stands in for a route chunk the network could not deliver:
// a rejected lazy module throws its rejection on every render, as this does.
vi.mock("../../src/presentation/examples/state-gallery-page.tsx", () => ({
default: function UnreachableChunk(): never {
throw new TypeError(
"Failed to fetch dynamically imported module: /assets/states.js",
);
},
}));
function ChunkDefect(): never {
throw new TypeError("Failed to fetch dynamically imported module");
@@ -27,6 +43,47 @@ describe("chunk recovery boundary classification", () => {
expect(isChunkLoadFailure(new Error("ordinary render defect"))).toBe(false);
});
it("recognizes the WebKit module failure and the Vite CSS preload failure", () => {
expect(
isChunkLoadFailure(new TypeError("Importing a module script failed.")),
).toBe(true);
expect(
isChunkLoadFailure(
new Error("Unable to preload CSS for /assets/states-3f2a.css"),
),
).toBe(true);
});
it("recovers when Vite rethrows a vite:preloadError into the lazy import", async () => {
// Vite dispatches `vite:preloadError` and, unless a listener prevents it,
// rejects the dynamic import with the same error. That rejection is what
// reaches this boundary.
const Page = lazy(() =>
Promise.reject(new Error("Unable to preload CSS for /assets/states.css")),
);
const recover = vi.fn(async () => ({
action: "support" as const,
reason: "reload-already-attempted",
}));
render(
<Suspense fallback={null}>
<ChunkRecoveryBoundary chunkId="route-states" recover={recover}>
<Page />
</ChunkRecoveryBoundary>
</Suspense>,
);
expect(
await screen.findByRole("heading", {
name: "화면 자산을 복구하지 못했습니다.",
}),
).toBeVisible();
expect(recover).toHaveBeenCalledWith({
chunkId: "route-states",
failureKind: "CHUNK_LOAD_FAILURE",
});
});
it("runs the recovery input only for a lazy chunk rejection", async () => {
const recover = vi.fn(async () => ({
action: "support" as const,
@@ -65,4 +122,56 @@ describe("chunk recovery boundary classification", () => {
);
expect(recover).not.toHaveBeenCalled();
});
it("offers a user-started reload on the failure surface", async () => {
render(
<ChunkRecoveryBoundary
chunkId="route-home"
recover={async () => ({
action: "support" as const,
reason: "reload-already-attempted",
})}
>
<ChunkDefect />
</ChunkRecoveryBoundary>,
);
expect(
await screen.findByRole("button", { name: "한 번 새로고침" }),
).toBeVisible();
});
it("clears a failed route chunk when the user moves to a sibling route", async () => {
// React Router reuses the rendered-route instance between sibling routes,
// so a failure latched in one route's boundary would otherwise follow the
// user to every other page until a full reload.
const user = userEvent.setup();
window.history.pushState({}, "", "/examples/states");
render(
<ApplicationProvider application={createTestApplication()}>
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>,
);
expect(
await screen.findByRole("heading", {
name: "화면 자산을 복구하지 못했습니다.",
}),
).toBeVisible();
await user.click(screen.getAllByRole("link", { name: "UI 구성요소" })[0]!);
expect(
await screen.findByRole(
"heading",
{ name: "UI 구성요소", level: 1 },
{ timeout: 5000 },
),
).toBeVisible();
expect(
screen.queryByRole("heading", { name: "화면 자산을 복구하지 못했습니다." }),
).toBeNull();
});
});
@@ -0,0 +1,129 @@
// @vitest-environment jsdom
import { act, render, screen, waitFor } from "@testing-library/react";
import { describe, expect, it, vi } from "vitest";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
/**
* Three bounded contexts cut from the real reference routes, so canonical
* redirects and access rules stay valid: A owns the list, B the status page,
* and the third one's routes module fails to download.
*/
vi.mock("../../src/apps/template-app.ts", async () => {
const { FEATURE_CONTEXT_ROUTES } = await import(
"../../src/features/reference-feature/context-routes.ts"
);
const only = (id: string) => async () =>
FEATURE_CONTEXT_ROUTES.filter((route) => route.id === id);
return {
TEMPLATE_APP_MODULE: {
id: "two-context-app",
budget: { maxContexts: 3 },
contexts: [
{
id: "context-a",
route: {
path: "examples/reference-resources/*",
loadRoutes: only("REFERENCE_RESOURCE_LIST"),
},
},
{
id: "context-b",
route: {
path: "examples/reference-resources/status/*",
loadRoutes: only("REFERENCE_RESOURCE_STATUS"),
},
},
{
id: "context-offline",
route: {
path: "examples/reference-resources/new/*",
loadRoutes: async () => {
throw new TypeError(
"Failed to fetch dynamically imported module: /assets/context-routes.js",
);
},
},
},
],
},
};
});
function navigateByHistory(url: string) {
act(() => {
window.history.pushState({}, "", url);
window.dispatchEvent(new PopStateEvent("popstate"));
});
}
function reportedRoutes(record: ReturnType<typeof vi.fn>): string[] {
return record.mock.calls
.map(([event]) => event as { eventId: string; context: { route_id: string } })
.filter((event) => event.eventId === "route.changed")
.map((event) => event.context.route_id);
}
describe("context route gateway", () => {
it("never matches a new context's URL against the previous context's routes", async () => {
const record = vi.fn();
window.history.pushState({}, "", "/examples/reference-resources");
render(
<ApplicationProvider
application={createTestApplication({ diagnostics: { record } })}
>
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>,
);
await waitFor(() =>
expect(reportedRoutes(record)).toContain("REFERENCE_RESOURCE_LIST"),
);
navigateByHistory("/examples/reference-resources/status");
await waitFor(() =>
expect(reportedRoutes(record)).toContain("REFERENCE_RESOURCE_STATUS"),
);
expect(reportedRoutes(record)).not.toContain("NOT_FOUND");
});
it("sends a failed routes-module download through chunk recovery", async () => {
const reload = vi.fn();
const release = (buildId: string, releaseId: string) => ({
buildId,
releaseId,
configSchemaVersion: "1",
apiContractVersion: "1",
assetManifestHash: "hash",
routeChunks: { "route-reference-resource-form": "assets/form.js" },
});
window.history.pushState({}, "", "/examples/reference-resources/new");
render(
<ApplicationProvider
application={createTestApplication({
navigation: { reload },
// A deploy happened: the page runs build-a, the server has build-b.
releaseInfo: {
getCurrent: async () => release("build-a", "release-a"),
refresh: async () => release("build-b", "release-b"),
},
})}
>
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>,
);
await waitFor(() => expect(reload).toHaveBeenCalledOnce());
expect(
await screen.findByText("새 버전으로 한 번만 전환합니다."),
).toBeVisible();
});
});
@@ -150,6 +150,40 @@ describe("design-system platform interactions", () => {
await waitFor(() => expect(trigger).toHaveFocus());
});
it("does not pull back focus that moved out of a closed drawer", async () => {
// A route change focuses the new page in the same tick the drawer closes;
// the drawer's deferred restore must not take that focus back.
const user = userEvent.setup();
function Harness() {
const [open, setOpen] = useState(false);
return (
<>
<Button onClick={() => setOpen(true)}>탐색 열기</Button>
<h1 tabIndex={-1}>새 페이지</h1>
<Drawer onClose={() => setOpen(false)} open={open} title="탐색">
<Button
onClick={() => {
setOpen(false);
queueMicrotask(() =>
screen.getByRole("heading", { name: "새 페이지" }).focus(),
);
}}
>
이동
</Button>
</Drawer>
</>
);
}
render(<Harness />);
await user.click(screen.getByRole("button", { name: "탐색 열기" }));
await user.click(screen.getByRole("button", { name: "이동" }));
await act(() => new Promise((resolve) => setTimeout(resolve, 20)));
expect(screen.getByRole("heading", { name: "새 페이지" })).toHaveFocus();
});
it("bounds the toast queue and collapses duplicate IDs", async () => {
const user = userEvent.setup();
function Harness() {
+42
View File
@@ -16,6 +16,10 @@ import {
useLocale,
type SupportedLocale,
} from "../../src/presentation/i18n/index.ts";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
function LocaleHarness() {
const { direction, locale, message, setLocale } = useLocale();
@@ -118,3 +122,41 @@ describe("locale provider runtime", () => {
expect(screen.queryByRole("img")).not.toBeInTheDocument();
});
});
describe("persisted locale preference", () => {
it("stores the chosen locale and starts the next mount from it", async () => {
const user = userEvent.setup();
const stored = new Map<string, unknown>();
const application = createTestApplication({
preferences: {
read: (name) => ({ ok: true as const, value: stored.get(name) }),
write: (name, value) => {
stored.set(name, value);
return { ok: true as const };
},
remove: (name) => {
stored.delete(name);
return { ok: true as const };
},
},
});
const mount = () =>
render(
<ApplicationProvider application={application}>
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>,
);
window.history.pushState({}, "", "/missing");
const first = mount();
await user.selectOptions(await screen.findByLabelText("언어"), "en-US");
expect(stored.get("LOCALE")).toBe("en-US");
first.unmount();
mount();
expect(await screen.findByLabelText("Language")).toHaveValue("en-US");
expect(document.documentElement).toHaveAttribute("lang", "en-US");
});
});
@@ -7,6 +7,7 @@ import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
import { INSTALLED_PRODUCT_FEATURE_IDS } from "../../src/features/installed-product-manifest.ts";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
import { createProductFeaturesStub } from "../helpers/runtime-capabilities-stub.ts";
@@ -38,7 +39,9 @@ function renderAt(path: string, disabled: boolean) {
: {}),
})}
>
<AppRouter />
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>,
);
}
+123 -4
View File
@@ -1,26 +1,51 @@
// @vitest-environment jsdom
import { render, screen, waitFor } from "@testing-library/react";
import { act, render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it } from "vitest";
import { describe, expect, it, vi } from "vitest";
import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.ts";
import type { ApplicationOutputPorts } from "../../src/application/create-application.ts";
import { INSTALLED_PRODUCT_FEATURE_IDS } from "../../src/features/installed-product-manifest.ts";
import { ApplicationProvider } from "../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../helpers/create-test-application.ts";
import { createProductFeaturesStub } from "../helpers/runtime-capabilities-stub.ts";
function renderRouter() {
function renderRouter(
diagnostics: ApplicationOutputPorts["diagnostics"] = { record: () => {} },
productFeatures?: ApplicationOutputPorts["productFeatures"],
) {
return render(
<ApplicationProvider
application={createTestApplication({
session: createAnonymousSessionAdapter(),
diagnostics,
...(productFeatures ? { productFeatures } : {}),
})}
>
<AppRouter />
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>,
);
}
/** A back/forward style navigation that leaves focus where the user left it. */
function navigateByHistory(url: string) {
act(() => {
window.history.pushState({}, "", url);
window.dispatchEvent(new PopStateEvent("popstate"));
});
}
function routeChangeReports(record: ReturnType<typeof vi.fn>) {
return record.mock.calls.filter(
([event]) => (event as { eventId: string }).eventId === "route.changed",
).length;
}
describe("generic application router", () => {
it("reaches the platform overview from the home starter actions", async () => {
const user = userEvent.setup();
@@ -81,6 +106,100 @@ describe("generic application router", () => {
);
});
it("changes only the title and copy when the locale changes", async () => {
// docs/architecture/routing-pages-and-patterns.md §9: a locale change
// re-renders the document title and copy; it is not a route change.
const user = userEvent.setup();
const record = vi.fn();
window.history.pushState({}, "", "/missing");
renderRouter({ record });
await waitFor(() =>
expect(
screen.getByRole("heading", {
name: "페이지를 찾을 수 없습니다.",
level: 1,
}),
).toHaveFocus(),
);
const reportsBefore = routeChangeReports(record);
expect(reportsBefore).toBeGreaterThan(0);
const localeSelect = screen.getByLabelText("언어");
await user.selectOptions(localeSelect, "en-US");
await waitFor(() =>
expect(document.title).toBe("Page not found · Frontend Skeleton"),
);
expect(
screen.getByRole("heading", { name: "Page not found.", level: 1 }),
).toBeVisible();
expect(localeSelect).toHaveFocus();
expect(routeChangeReports(record)).toBe(reportsBefore);
});
it.each([
{
surface: "authentication-required",
url: "/examples/reference-resources",
routeId: "REFERENCE_RESOURCE_LIST",
title: "Reference resources · Frontend Skeleton",
disableFeature: false,
},
{
surface: "invalid-route",
url: "/examples/ui?unexpected=1",
routeId: "EXAMPLES_UI",
title: "UI 구성요소 · Frontend Skeleton",
disableFeature: false,
},
{
surface: "disabled-feature",
url: "/examples/reference-resources",
routeId: "REFERENCE_RESOURCE_LIST",
title: "Reference resources · Frontend Skeleton",
disableFeature: true,
},
])(
"runs the route lifecycle on the $surface surface",
async ({ surface, url, routeId, title, disableFeature }) => {
const record = vi.fn();
window.history.pushState({}, "", "/");
const { container } = renderRouter(
{ record },
disableFeature
? createProductFeaturesStub({
[INSTALLED_PRODUCT_FEATURE_IDS[0]!]: "DISABLED_BY_CONFIG",
})
: undefined,
);
const link = (
await screen.findAllByRole("link", { name: "UI 구성요소" })
)[0]!;
link.focus();
navigateByHistory(url);
await waitFor(
() =>
expect(
container.querySelector(`[data-surface="${surface}"]`),
).not.toBeNull(),
{ timeout: 5000 },
);
await waitFor(() => expect(document.title).toBe(title));
expect(
screen.getByRole("main").contains(document.activeElement),
).toBe(true);
expect(record).toHaveBeenCalledWith(
expect.objectContaining({
eventId: "route.changed",
context: expect.objectContaining({ route_id: routeId }),
}),
);
},
);
it("focuses the route heading again when the lazy chunk is already cached", async () => {
// §9.7. The first visit resolves the route module asynchronously, so the
// router lifecycle and the page header commit separately. A later visit
@@ -1,6 +1,7 @@
// @vitest-environment jsdom
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { describe, expect, it, vi } from "vitest";
import { createRuntimeComposition } from "../../src/bootstrap/create-runtime-composition.ts";
@@ -71,4 +72,53 @@ describe("production runtime application tree", () => {
expect(fetcher).toHaveBeenCalledTimes(2);
expect(composition).not.toHaveProperty("ports");
});
it("keeps locale state across a session scope fence and disposes routers", async () => {
const user = userEvent.setup();
const fetcher = vi.fn(async (input: RequestInfo | URL) => {
const url =
typeof input === "string"
? input
: input instanceof URL
? input.href
: input.url;
return Response.json(
url.includes("release-manifest") ? releaseManifest : runtimeConfig,
);
});
window.localStorage.clear();
const composition = await createRuntimeComposition({
fetcher,
host: { localStorage: window.localStorage },
});
// Spies call through; each router's history listens to popstate.
const add = vi.spyOn(window, "addEventListener");
const remove = vi.spyOn(window, "removeEventListener");
const popstateCalls = (spy: typeof add | typeof remove) =>
spy.mock.calls.filter(([type]) => type === "popstate").length;
try {
window.history.pushState({}, "", "/missing");
const app = render(<RuntimeApplication composition={composition} />);
await user.selectOptions(await screen.findByLabelText("언어"), "en-US");
// Only the live provider holds the choice from here on; a remount would
// start over from empty storage.
window.localStorage.clear();
// Demo sign-in changes the session: the scope goes FENCED, then READY.
await user.click(screen.getByRole("button", { name: "Sign in" }));
expect(
await screen.findByRole("button", { name: "Sign out" }),
).toBeVisible();
expect(screen.getByLabelText("Language")).toHaveValue("en-US");
app.unmount();
expect(popstateCalls(add)).toBeGreaterThan(0);
expect(popstateCalls(remove)).toBe(popstateCalls(add));
} finally {
add.mockRestore();
remove.mockRestore();
await composition.dispose();
}
});
});
@@ -189,6 +189,87 @@ describe("feature HTTP binding", () => {
expect(result.error.code).toBe("MAPPING_INVARIANT_REJECTED");
});
it.each([
"FINAL_REQUEST_INVARIANT_FAILED",
"MISSING_IDEMPOTENCY_KEY",
"UNEXPECTED_IDEMPOTENCY_KEY",
] as const)(
"does not report the request-side violation %s as a server envelope mismatch",
async (violationKind) => {
const scripted = scriptedExecutor<ResourceWire, ResourceProblem>(
Object.freeze({
kind: "CONTRACT_VIOLATION" as const,
violation: Object.freeze({
kind: violationKind,
operation: "REQUEST" as const,
}),
effect: "NOT_APPLICABLE" as const,
}),
);
const binding = createFeatureHttpBinding(scripted.executor, OPERATIONS);
const result = await binding.execute("LOAD_RESOURCE", {
resourceId: "resource-1",
});
expect(result).toMatchObject({
ok: false,
error: { kind: "VALIDATION_REJECTED", code: violationKind },
});
},
);
it.each([
[
"mapSuccess",
Object.freeze({
kind: "SUCCESS" as const,
value: Object.freeze({ id: "resource-1", title: "Reference" }),
metadata: Object.freeze({ status: 201 }),
effect: "APPLIED_CONFIRMED" as const,
}),
],
[
"mapProblem",
Object.freeze({
kind: "PROBLEM" as const,
problem: Object.freeze({ code: "RESOURCE_NAME_EXISTS" }),
metadata: Object.freeze({ status: 409 }),
effect: "APPLIED_CONFIRMED" as const,
}),
],
])(
"returns a mapping failure with the server effect when %s throws",
async (_mapper, outcome) => {
const scripted = scriptedExecutor<ResourceWire, ResourceProblem>(outcome);
const binding = createFeatureHttpBinding(scripted.executor, {
LOAD_RESOURCE: defineFeatureHttpOperation({
contract: LOAD_RESOURCE_CONTRACT,
routeId: "RESOURCE_DETAIL",
mapSuccess(): never {
throw new TypeError("mapper defect");
},
mapProblem(): never {
throw new TypeError("mapper defect");
},
}),
} as const);
const result = await binding.execute("LOAD_RESOURCE", {
resourceId: "resource-1",
});
expect(result).toMatchObject({
ok: false,
error: {
kind: "MAPPING_CONTRACT_VIOLATION",
code: "MAPPING_CONTRACT_VIOLATION",
effect: "APPLIED_CONFIRMED",
},
});
},
);
it("lets the feature interpret a typed business problem", async () => {
const scripted = scriptedExecutor<ResourceWire, ResourceProblem>(
Object.freeze({
@@ -29,6 +29,7 @@ import { MutationIntentProvider } from "../../../src/presentation/adapters/query
import { ServerStateScopeProvider } from "../../../src/presentation/adapters/query/server-state-scope-provider.tsx";
import { createServerStateScopeRuntime } from "../../../src/adapters/query-cache/server-state-scope-runtime.ts";
import { ApplicationProvider } from "../../../src/presentation/providers/application-provider.tsx";
import { PreferenceProviders } from "../../../src/presentation/providers/preference-providers.tsx";
import { AppRouter } from "../../../src/presentation/routes/app-router.tsx";
import { createTestApplication } from "../../helpers/create-test-application.ts";
@@ -84,7 +85,9 @@ function renderReference(
featureInputs: { [REFERENCE_FEATURE_ID]: input },
})}
>
<AppRouter />
<PreferenceProviders>
<AppRouter />
</PreferenceProviders>
</ApplicationProvider>
</QueryInvalidationProvider>
</ServerStateScopeProvider>
@@ -1,5 +1,6 @@
import { describe, expect, it, vi } from "vitest";
import type { DemoSessionAdapter } from "../../../src/adapters/auth/external-session-adapter.ts";
import { createRuntimeAdapters } from "../../../src/bootstrap/runtime-adapters.ts";
import { createRuntimeIdentityRegistry } from "../../../src/contracts/query-keys.ts";
import { bindQuery } from "../../../src/contracts/server-state.ts";
@@ -210,4 +211,59 @@ describe("reference feature runtime composition", () => {
expect(safeEvidence).not.toContain("private-idempotency-key");
adapters.infrastructure.dispose();
});
/**
* R-3.2. A request refused before dispatch because no credential exists is
* not a session verdict. Reporting it to the owner overwrote a recovering
* session and could loop through the scope fence; only a server 401 may.
*/
it("does not report a request refused before dispatch as a sign-out", async () => {
const fetcher = vi.fn(async () => Response.json([]));
const adapters = await createRuntimeAdapters({
runtime,
release,
host: {},
fetcher,
});
const session = adapters.outputPorts.session as DemoSessionAdapter;
session.setState("recovery-pending");
await vi.waitFor(() =>
expect(adapters.infrastructure.serverStateScope.getPhase()).toBe("READY"),
);
const notifications = vi.fn();
session.subscribe(notifications);
await expect(
referenceInput(adapters).listResources({ limit: 20 }),
).resolves.toMatchObject({ ok: false });
expect(fetcher).not.toHaveBeenCalled();
expect(session.getState()).toBe("recovery-pending");
expect(notifications).not.toHaveBeenCalled();
adapters.infrastructure.dispose();
});
it("still signs out when the server answers 401", async () => {
const fetcher = vi.fn(
async () => new Response(null, { status: 401 }),
);
const adapters = await createRuntimeAdapters({
runtime,
release,
host: {},
fetcher,
});
await adapters.outputPorts.session.beginSignIn();
await vi.waitFor(() =>
expect(adapters.infrastructure.serverStateScope.getPhase()).toBe("READY"),
);
await expect(
referenceInput(adapters).listResources({ limit: 20 }),
).resolves.toMatchObject({ ok: false });
expect(fetcher).toHaveBeenCalledOnce();
expect(adapters.outputPorts.session.getState()).toBe("unauthenticated");
adapters.infrastructure.dispose();
});
});
@@ -3,7 +3,10 @@ import { describe, expect, it, vi } from "vitest";
import { createReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.ts";
import { createFailure } from "../../../src/contracts/errors.ts";
import type { TelemetryPort } from "../../../src/platform/telemetry/telemetry-port.ts";
import { createTelemetryPipeline } from "../../../src/platform/telemetry/telemetry-pipeline.ts";
import {
createTelemetryPipeline,
type TelemetryTransport,
} from "../../../src/platform/telemetry/telemetry-pipeline.ts";
import { REFERENCE_FEATURE_ADAPTER_CONTRIBUTION } from "../../../src/features/reference-feature/adapters/create-reference-feature-input.ts";
function failingGateway() {
@@ -55,14 +58,19 @@ describe("reference feature telemetry through the platform port", () => {
});
it("collapses a failure storm into bounded sends via the pipeline", async () => {
const send = vi.fn();
const send = vi.fn<TelemetryTransport["send"]>();
const pipeline = createTelemetryPipeline({ transport: { send } });
const input = createReferenceFeatureInput(failingGateway(), { telemetry: pipeline });
for (let i = 0; i < 500; i += 1) await input.listResources({ limit: 20 });
await pipeline.flush();
expect(send).toHaveBeenCalledTimes(1);
// The first failure goes out at once; the 499 duplicates ride on the flush.
expect(send).toHaveBeenCalledTimes(2);
const occurrences = send.mock.calls
.flatMap(([batch]) => batch)
.reduce((sum, item) => sum + item.occurrences, 0);
expect(occurrences).toBe(500);
expect(pipeline.stats().deduplicated).toBe(499);
pipeline.dispose();
});
@@ -281,6 +281,50 @@ describe("LIVE-01 credential integration failures are not user session failures"
);
});
/**
* R-3.4. Fetch rejects a header value that is not a control-free ByteString.
* Letting that reach `fetch()` reported an auth defect as a network failure
* after dispatch (MAYBE_APPLIED for a command).
*/
it.each([
["NUL", "Bearer abc\u0000def"],
["non-Latin-1", "Bearer 한"],
])(
"rejects a %s credential value before dispatch",
async (_label, value) => {
const fetcher = vi.fn(
async (_url: RequestInfo | URL, init?: RequestInit) => {
new Headers(init?.headers);
return jsonResponse([]);
},
);
const executor = createContractHttpExecutor({
baseUrl: "https://api.example/",
maxRetryAttempts: 0,
authProfiles: TEST_PROFILES,
attachCredentials: () =>
Object.freeze({
kind: "READY" as const,
headers: Object.freeze({ authorization: value }),
}),
fetcher: fetcher as unknown as typeof fetch,
});
const outcome = await executor.execute(
bearerOperation(),
{ limit: 1 },
{ routeId: ROUTE_ID, scope: scopeSnapshot() },
);
expect(outcome).toMatchObject({
kind: "AUTH_INTEGRATION_FAILURE",
reason: "CREDENTIAL_HEADER_VALUE_INVALID",
effect: "NOT_APPLICABLE",
});
expect(fetcher).not.toHaveBeenCalled();
},
);
it("still reports a real absent session as UNAUTHENTICATED", async () => {
const fetcher = vi.fn(async () => jsonResponse([]));
const executor = createContractHttpExecutor({
@@ -57,16 +57,29 @@ describe("release mismatch recovery", () => {
expect(recovery.decide("R10->R11")).toBe("reload-once");
});
it("keeps a single bounded marker and scopes it to the mismatch key", () => {
it("keeps a single bounded marker", () => {
const storage = markerStore();
const recovery = createReleaseMismatchRecovery(storage);
expect(recovery.decide("R10->R11")).toBe("reload-once");
expect(recovery.decide("R11->R12")).toBe("reload-once");
expect(storage.values.size).toBe(1);
expect(recovery.decide("x".repeat(10_000))).toBe("reload-once");
expect(storage.values.size).toBe(1);
expect([...storage.values.values()][0]?.length).toBeLessThan(300);
});
it("allows one automatic reload per session within the TTL whatever the key", () => {
const recovery = createReleaseMismatchRecovery(markerStore());
expect(recovery.decide("A")).toBe("reload-once");
expect(recovery.decide("B")).toBe("show-failure");
expect(recovery.decide("A")).toBe("show-failure");
});
it("cannot loop when a load balancer alternates the mismatch key", () => {
const recovery = createReleaseMismatchRecovery(markerStore());
const decisions = Array.from({ length: 20 }, (_, boot) =>
recovery.decide(boot % 2 === 0 ? "build-R10:X:R11" : "build-R11:X:R10"),
);
expect(decisions.filter((decision) => decision === "reload-once")).toHaveLength(1);
});
it("lets an expired marker recover again instead of blocking forever", () => {
let now = 0;
const recovery = createReleaseMismatchRecovery(markerStore(), {
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vitest";
import {
DEFAULT_TELEMETRY_PAYLOAD_BUDGET,
REDACTED,
redactTelemetryPayload,
TRUNCATED,
@@ -34,6 +35,98 @@ describe("redactTelemetryPayload", () => {
expect(result).toEqual({ note: REDACTED, jwt: REDACTED, list: [REDACTED] });
});
it("keeps legitimate telemetry values and innocent keys untouched", () => {
const legitimate = {
reason: "REQUEST_TIMEOUT",
operation: "LIST_REFERENCE_RESOURCES",
routeId: "reference.resources.detail",
featureId: "reference-feature",
resourceId: "01J8Z3K7Q9W4N2B6C5D1E0F7GH",
uuid: "3f2a9c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
traceHex: "4bf92f3577b34da6a3ce929d0e0e4736",
plan: "BASIC_PLAN",
dependency: "react@19.1.0",
path: "/api/resources?limit=20&cursor=c1#top",
message: "error code=REQUEST_TIMEOUT after 3 attempts",
status: 404,
durationMs: 12.5,
retried: false,
spinner: "visible",
author: "system",
compass: "north",
opinion: "none",
shipping: "standard",
isPinned: true,
code: "E_CONFLICT",
key: "sort-order",
};
expect(redactTelemetryPayload(legitimate)).toEqual(legitimate);
});
it.each([
"pwd",
"pass",
"auth",
"otp",
"pin",
"userPwd",
"pin_code",
"PINCode",
"x-otp",
"authHeader",
"passcode",
])("redacts the short secret key %s as a whole key token", (secretKey) => {
const result = redactTelemetryPayload({ [secretKey]: "s3cr3t", safe: "ok" });
expect(result).toEqual({ safe: "ok" });
});
it("redacts credentials in the middle of a string", () => {
expect(
redactTelemetryPayload({
header: "request failed: Authorization: Bearer abc",
basic: "proxy said Basic dXNlcjpwYXNz was rejected",
jwt: "retry with eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.c2lnbmF0dXJl now",
}),
).toEqual({
header: `request failed: Authorization: ${REDACTED}`,
basic: `proxy said ${REDACTED} was rejected`,
jwt: `retry with ${REDACTED} now`,
});
});
it("masks secret URL query and fragment parameters", () => {
expect(
redactTelemetryPayload(
"GET https://api.example.com/cb?code=abc123&state=xyz&access_token=tok456&key=k1#id_token=jwt789",
),
).toBe(
`GET https://api.example.com/cb?code=${REDACTED}&state=xyz&access_token=${REDACTED}&key=${REDACTED}#id_token=${REDACTED}`,
);
expect(redactTelemetryPayload("/login?user=a&password=hunter2&otp=123456")).toBe(
`/login?user=a&password=${REDACTED}&otp=${REDACTED}`,
);
});
it("masks email addresses", () => {
expect(
redactTelemetryPayload({ note: "invite failed for jane.doe+test@example.co.uk twice" }),
).toEqual({ note: `invite failed for ${REDACTED} twice` });
});
it("does not leak a secret cut in half by truncation", () => {
const budget = { ...DEFAULT_TELEMETRY_PAYLOAD_BUDGET, maxStringLength: 32 };
const cut = redactTelemetryPayload(
{
email: `${"x".repeat(20)} jane.doe@example.com`,
query: `/cb${"x".repeat(10)}?access_token=abcdefghijklmnopqrstuvwxyz`,
bearer: `${"x".repeat(20)} Bearer abcdefghijklmnopqrstuvwxyz`,
},
budget,
);
expect(JSON.stringify(cut)).not.toMatch(/jane|abcd/u);
expect(JSON.stringify(cut)).toContain(TRUNCATED);
});
it("never invokes getters, toJSON or foreign prototypes", () => {
let invoked = false;
class Carrier {
@@ -101,6 +101,88 @@ describe("createTelemetryPipeline", () => {
expect(batches[0]?.[0]?.occurrences).toBe(25);
});
it("delivers every duplicate as occurrences with the default microtask scheduler", async () => {
const batches: TelemetryBatchItem[][] = [];
const pipeline = createTelemetryPipeline({
transport: { send: (batch) => void batches.push([...batch]) },
budget: TEST_TELEMETRY_BUDGET,
});
for (let i = 0; i < 1_000; i += 1) {
await pipeline.emit(REPEATED_ERROR);
}
await pipeline.flush();
const items = batches.flat();
expect(items.reduce((sum, item) => sum + item.occurrences, 0)).toBe(1_000);
expect(new Set(items.map((item) => item.fingerprint)).size).toBe(1);
expect(batches.length).toBeLessThanOrEqual(2);
pipeline.dispose();
});
it("reports held duplicates when the dedup window closes without another flush", async () => {
const batches: TelemetryBatchItem[][] = [];
const timers: Array<Readonly<{ callback: () => void; ms: number }>> = [];
const pipeline = createTelemetryPipeline({
transport: { send: (batch) => void batches.push([...batch]) },
budget: TEST_TELEMETRY_BUDGET,
setTimer: (callback, ms) => timers.push({ callback, ms }),
clearTimer: () => {},
});
for (let i = 0; i < 10; i += 1) {
await pipeline.emit(REPEATED_ERROR);
}
expect(timers.map((timer) => timer.ms)).toEqual([TEST_TELEMETRY_BUDGET.dedupWindowMs]);
for (const timer of timers.splice(0)) timer.callback();
await new Promise((resolve) => setTimeout(resolve, 0));
expect(batches.flat().reduce((sum, item) => sum + item.occurrences, 0)).toBe(10);
pipeline.dispose();
});
it("does not let a rejected or evicted event suppress its fingerprint", async () => {
const batches: TelemetryBatchItem[][] = [];
const pipeline = createTelemetryPipeline({
transport: { send: (batch) => void batches.push([...batch]) },
budget: { ...TEST_TELEMETRY_BUDGET, maxBufferedEvents: 1 },
schedule: () => {},
});
const info: TelemetryEvent<unknown> = { ...TEST_EVENT, kind: "catalog.load.slow", severity: "info" };
// Rejected on arrival: the buffer holds a more important event.
await pipeline.emit(TEST_EVENT);
await pipeline.emit(info);
await pipeline.flush();
await pipeline.emit(info);
expect(pipeline.stats()).toMatchObject({ buffered: 1, deduplicated: 0 });
await pipeline.flush();
// Evicted after admission: a more important event takes its slot.
await pipeline.emit({ ...info, payload: { reason: "evicted" } });
await pipeline.emit({ ...TEST_EVENT, payload: { reason: "other" } });
await pipeline.flush();
await pipeline.emit({ ...info, payload: { reason: "evicted" } });
expect(pipeline.stats()).toMatchObject({ buffered: 1, deduplicated: 0 });
await pipeline.flush();
const kinds = batches.flat().map((item) => `${item.event.kind}:${item.occurrences}`);
expect(kinds).toEqual([
"catalog.load.failed:1",
"catalog.load.slow:1",
"catalog.load.failed:1",
"catalog.load.slow:1",
]);
});
it("never reports a sampled-out event through a duplicate summary", async () => {
const send = vi.fn();
const pipeline = createTelemetryPipeline({
transport: { send },
budget: { ...TEST_TELEMETRY_BUDGET, sampleRate: 0 },
});
for (let i = 0; i < 3; i += 1) {
await pipeline.emit({ kind: "a.info", severity: "info" });
}
await pipeline.flush();
expect(send).not.toHaveBeenCalled();
expect(pipeline.stats().sampledOut).toBe(3);
pipeline.dispose();
});
it("rate-limits distinct events and resumes after the window reopens", async () => {
let now = 0;
const scheduling = manualScheduling();
+14
View File
@@ -101,4 +101,18 @@ describe("mixed-replica routing during a rolling release", () => {
expect(session.final).toMatchObject({ state: "release-mismatch", applicationMounted: false });
expect(storage.size()).toBe(1);
});
it("cannot reload-loop when replicas alternate between two different mismatches", async () => {
const sequences = [
[response("html", "R10"), response("config", "R11"), response("manifest", "R10")],
[response("html", "R11"), response("config", "R10"), response("manifest", "R11")],
];
let boot = 0;
const session = await runBootSession(
() => sequences[boot++ % sequences.length] ?? [],
createReleaseMismatchRecovery(memoryStorage()),
);
expect(session.reloads).toBe(1);
expect(session.final).toMatchObject({ state: "release-mismatch", applicationMounted: false });
});
});
@@ -53,18 +53,81 @@ describe("runtime configuration boundary", () => {
{ ...validConfig, RELEASE_MANIFEST_URL: "/manifest.json?v=1" },
"§6.2 query in manifest URL",
],
[
{ ...validConfig, RELEASE_MANIFEST_URL: "/\t/evil.example/m.json" },
"R-7.3 tab turns the path into a protocol-relative URL",
],
[
{ ...validConfig, RELEASE_MANIFEST_URL: "/\n/evil.example/m.json" },
"R-7.3 newline is stripped by the URL parser",
],
[
{ ...validConfig, RELEASE_MANIFEST_URL: "/a/%2e%2e/b.json" },
"R-7.3 encoded dot segment",
],
[
{ ...validConfig, RELEASE_MANIFEST_URL: "/a/%2E/b.json" },
"R-7.3 encoded single dot segment",
],
[{ ...validConfig, UNKNOWN_KEY: true }, "unknown key"],
])("rejects invalid config: %s (%s)", (candidate, _reason) => {
void _reason;
expect(validateRuntimeConfig(candidate).success).toBe(false);
});
it.each(["/release-manifest.json", "/app/v1/release-manifest.json", "/a/.well-known/m.json"])(
"accepts a same-origin manifest path: %s",
(RELEASE_MANIFEST_URL) => {
expect(
validateRuntimeConfig({ ...validConfig, RELEASE_MANIFEST_URL }).success,
).toBe(true);
},
);
it("rejects secret-like names before schema validation", () => {
expect(() => assertSafeConfigNames({ CLIENT_SECRET: "not-safe" })).toThrow(
"Forbidden client configuration key",
);
});
// R-7.2. FEATURE_OVERRIDES keys are feature ids (data), not configuration
// names; a kill switch for `cookie-consent` must not fail boot.
it("loads a config whose FEATURE_OVERRIDES name a secret-looking feature id", async () => {
const result = await loadRuntimeConfig({
buildConfig: {
buildId: "build-a",
commitSha: "local",
routerBasePath: "/",
runtimeConfigUrl: "/config.json",
},
fetcher: async () =>
new Response(
JSON.stringify({
...validConfig,
FEATURE_OVERRIDES: {
"cookie-consent": "DISABLED",
"password-reset": "DISABLED",
"token-wallet": "DEFAULT",
},
}),
{ headers: { "content-type": "application/json" } },
),
});
expect(result.config.FEATURE_OVERRIDES["cookie-consent"]).toBe("DISABLED");
});
it.each<[Record<string, unknown>, string]>([
[{ FEATURE_OVERRIDES: {}, CLIENT_SECRET: "x" }, "top level"],
[{ CAPABILITY_OVERRIDES: { AUTH_TOKEN: "DEFAULT" } }, "other nested map"],
[{ NESTED: { deeper: { PRIVATE_KEY: "x" } } }, "deeper nesting"],
[{ FEATURE_OVERRIDES: { alpha: { CLIENT_SECRET: "x" } } }, "below a feature id"],
])("still rejects forbidden names outside feature ids: %o (%s)", (candidate) => {
expect(() => assertSafeConfigNames(candidate)).toThrow(
"Forbidden client configuration key",
);
});
it("allows demo authentication only for local runtime configuration", () => {
expect(
validateRuntimeConfig({ ...validConfig, AUTH_MODE: "demo" }).success,
+55
View File
@@ -3,7 +3,9 @@ import { describe, expect, it } from "vitest";
import {
composeApiOperations,
defineRestOperation,
type RestOperationV2,
} from "../../src/contracts/api-operations.ts";
import { API_OPERATIONS } from "../../src/features/installed-feature-contracts.ts";
function operation(operationId = "GET_RESOURCE") {
return defineRestOperation({
@@ -56,3 +58,56 @@ describe("REST operation v2 registry", () => {
).toThrow("Incoherent REST replay contract");
});
});
function command(): RestOperationV2 {
return {
...operation(),
semantics: "COMMAND",
method: "POST",
path: "/resources",
operationId: "CREATE_RESOURCE",
idempotency: "keyed",
replayPolicy: "KEYED_COMMAND",
idempotencyKeyPolicy: "REQUIRED",
requestSource: "body",
pathSchema: "NoRequest",
pathParameterNames: [],
};
}
/**
* R-7.4. CSRF protection is chosen from the HTTP method, so a COMMAND sent
* as GET/HEAD would skip it. browser-rpc and the V3 composition already bind
* commands to unsafe methods; REST V2 must too.
*/
describe("REST operation v2 command method and enum rules", () => {
it.each(["POST", "PUT", "PATCH", "DELETE"])("accepts a COMMAND sent as %s", (method) => {
expect(defineRestOperation({ ...command(), method }).method).toBe(method);
});
it.each(["GET", "HEAD", "OPTIONS", "post"])("rejects a COMMAND sent as %s", (method) => {
expect(() => defineRestOperation({ ...command(), method })).toThrow(TypeError);
expect(() =>
composeApiOperations([{ CREATE_RESOURCE: { ...command(), method } }]),
).toThrow(TypeError);
});
it.each<[string, Record<string, unknown>]>([
["semantics", { semantics: "SUBSCRIBE" }],
["replayPolicy", { replayPolicy: "ALWAYS" }],
])("rejects an unknown %s value", (_field, patch) => {
void _field;
const candidate = { ...command(), ...patch } as unknown as RestOperationV2;
expect(() => defineRestOperation(candidate)).toThrow(TypeError);
});
it("keeps every installed REST v2 operation valid", () => {
for (const installed of Object.values(API_OPERATIONS)) {
if (installed.contractVersion !== 2) continue;
expect(
() => defineRestOperation(installed as RestOperationV2),
installed.operationId,
).not.toThrow();
}
});
});
+43
View File
@@ -68,6 +68,28 @@ describe("external AuthSessionPort adapter", () => {
).rejects.toThrow("forbidden credential patch");
});
it("rejects credential headers that differ only in case instead of merging them", async () => {
const adapter = createExternalAuthSessionAdapter({
readState: () => "authenticated",
subscribe: () => () => {},
beginSignIn: async () => {},
signOut: async () => {},
attachCredential: async () => ({
headers: { Authorization: "Bearer a", authorization: "Bearer b" },
}),
recoverSession: async () => "restored",
notifyUnauthenticated: vi.fn(),
});
await expect(
adapter.credentialPatch({
origin: "https://api.test",
method: "GET",
operationId: "GET_RESOURCE",
}),
).rejects.toThrow("forbidden credential patch");
});
it("provides a safe anonymous adapter", async () => {
const adapter = createAnonymousSessionAdapter();
expect(adapter.getState()).toBe("unauthenticated");
@@ -89,4 +111,25 @@ describe("external AuthSessionPort adapter", () => {
expect(notifications).toBe(2);
unsubscribe();
});
it("does not notify when the demo state is set to its current value", async () => {
const adapter = createDemoSessionAdapter("recovery-pending");
let notifications = 0;
adapter.subscribe(() => {
notifications += 1;
});
adapter.setState("recovery-pending");
expect(notifications).toBe(0);
adapter.setState("authenticated");
await adapter.beginSignIn();
expect(notifications).toBe(1);
adapter.onUnauthenticated();
adapter.onUnauthenticated();
await adapter.signOut();
expect(adapter.getState()).toBe("unauthenticated");
expect(notifications).toBe(2);
});
});
+96
View File
@@ -440,6 +440,38 @@ describe("browser download delivery", () => {
);
});
it("calls an injected window save picker without rebinding its receiver", async () => {
const events: string[] = [];
const adapter = createDownloadDeliveryAdapter({
...HARD_LIMITS,
policies,
host: { handoff: vi.fn() },
browserManagedCapabilities: capabilityResolver(),
// A Window operation throws "Illegal invocation" unless `this` is the
// Window. Web IDL maps an undefined `this` to the global object.
showSaveFilePicker: function (this: unknown) {
if (this !== undefined && this !== globalThis) {
throw new TypeError("Illegal invocation");
}
return Promise.resolve(writableHandle(events));
},
userActivation: { isActive: true },
});
expect(
await adapter.deliver(
deliveryInput(
{
kind: "GENERATED",
bytes: byteSource([new Uint8Array([1, 2])]),
},
"PROMPT_AND_STREAM",
),
),
).toMatchObject({ ok: true, value: { kind: "SAVED" } });
expect(events).toEqual(["write:2", "close"]);
});
it("snapshots the generated source before awaiting the save picker", async () => {
const events: string[] = [];
let resolvePicker:
@@ -746,6 +778,70 @@ describe("browser download delivery", () => {
expect(handoff).not.toHaveBeenCalled();
});
it("resolves ABORTED and closes a late lease when a bounded source open is aborted", async () => {
const controller = new AbortController();
let releaseOpen: ((value: unknown) => void) | undefined;
const close = vi.fn();
const handoff = vi.fn();
const record = vi.fn();
const adapter = createDownloadDeliveryAdapter({
...HARD_LIMITS,
policies,
host: { handoff },
browserManagedCapabilities: capabilityResolver(),
userActivation: { isActive: true },
observer: { record },
// Ignores the signal and resolves only when the test says so.
openAuthorizedSource: () =>
new Promise((resolve) => {
releaseOpen = resolve;
}) as never,
});
const capability = Object.freeze({
capabilityReceipt: "capability-bounded-1",
method: "GET" as const,
binding: { kind: "DOWNLOAD" as const, resourceId: "resource-1" },
mediaType: "application/pdf",
byteLength: 3,
maxBytes: 3,
expectedSha256: "a".repeat(64),
expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
});
const delivering = adapter.deliver(
deliveryInput(
{
kind: "AUTHORIZED_STREAM_RESOURCE",
resourceId: "resource-1",
capability: capability as never,
},
"BOUNDED_OBJECT_URL",
controller.signal,
),
);
await new Promise((resolve) => setTimeout(resolve, 0));
controller.abort();
await expect(delivering).resolves.toMatchObject({
ok: false,
error: { code: "ABORTED" },
});
expect(record).toHaveBeenCalled();
releaseOpen?.({
ok: true,
value: {
byteLength: 3,
integrity: "VERIFIED_ON_SUCCESSFUL_EXHAUSTION",
capability,
close,
async *stream() {},
},
});
await new Promise((resolve) => setTimeout(resolve, 0));
expect(close).toHaveBeenCalledOnce();
expect(handoff).not.toHaveBeenCalled();
});
it("rejects caller limits above runtime hard caps before side effects", async () => {
const handoff = vi.fn();
const showSaveFilePicker = vi.fn(async () => writableHandle([]));
+32
View File
@@ -416,6 +416,38 @@ describe("browser file pickers", () => {
});
});
it("calls an injected window picker without rebinding its receiver", async () => {
const harness = createHarness();
const picker = new EnhancedFilePicker({
// A Window operation throws "Illegal invocation" unless `this` is the
// Window. Web IDL maps an undefined `this` to the global object.
showOpenFilePicker: function (this: unknown) {
if (this !== undefined && this !== globalThis) {
throw new TypeError("Illegal invocation");
}
return Promise.resolve([
{
kind: "file" as const,
name: "safe.txt",
async getFile() {
return new File(["safe"], "safe.txt", {
type: "text/plain",
lastModified: 1,
});
},
},
]);
},
...harness,
userActivation: { isActive: true },
});
expect(await picker.select({ policy })).toMatchObject({
ok: true,
value: { kind: "SELECTED" },
});
});
it("rejects excessive enhanced selections before reading handles", async () => {
const getFile = vi.fn(async () => new File(["a"], "a.txt"));
const multiplePolicy = {

Some files were not shown because too many files have changed in this diff Show More