docs(operations): 운영 문서와 adapter 재검토 처리 원장을 한국어로 옮긴다

문제: docs/operations의 release-cache-rollback.md와
adapter-remediation-ledger.md는 본문이 영어이고, 나머지 복구 문서와
ci-quality-gates.md에도 영어 문단이 남아 있다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. 원장은 check:remediation-ledger가
읽으므로 같은 변경에서 스크립트를 맞춘다.
- `SECTION_HEADING`을 옮긴 절 제목(`## 세 번째 재검토 (2026-08-14)`)으로
- 「모두 닫혔다」를 잡는 `BLANKET_CLOSURE`에 한국어 대안을 더한다. 영어
  대안은 원장이 인용한 옛 문장을 잡도록 그대로 둔다
- 표 구조, id 칸, disposition 칸의 백틱 값, file-transfer 예산 숫자는
  그대로다
- ci-quality-gates.md의 advisory 표가 복사한 zod·react-router 버전을
  `package.json`·`pnpm-lock.yaml`을 가리키게 바꾼다(number 검사)

위험: check:remediation-ledger는 게이트 밖이라 CI가 돌리지 않는다.
desktop에서 손으로 돌려 확인했다.

검증: dispositions.json의 id 25개가 그 절의 행과 맞는지, 예산 숫자가
있는지를 스크립트로 확인했다. 문서 검사의 language·number 줄이 0이 되어
예외 목록에서 지웠다.
This commit is contained in:
DongHyeonka
2026-11-08 21:57:47 +09:00
parent af10cae9a6
commit 45e8cb774c
11 changed files with 785 additions and 924 deletions
+338 -438
View File
@@ -1,63 +1,54 @@
# Adapter Remediation Ledger
# Adapter 수정 원장
> Source of truth for the execution state of every confirmed finding in
> [`docs/reviews/adapters/`](../reviews/adapters/README.md).
> [`docs/reviews/adapters/`](../reviews/adapters/README.md)에서 확인된 모든 발견(finding)의 실행 상태를 적는 정본이다.
>
> Plan: 2026-08-13 adapter remediation, a work-history plan under docs/history/plans
> that a copied project may delete (README, "Files you can delete after copying").
> Baseline revision: `develop` / `4dc033cf33a5b6173bbf960d5eb464a406dc4c92`.
> 계획: 2026-08-13 adapter 수정 계획. docs/history/plans 아래의 작업 이력 계획이고, 복사한 프로젝트는 지워도 된다(README 「복사한 뒤 지워도 되는 것」).
> 기준 리비전: `develop` / `4dc033cf33a5b6173bbf960d5eb464a406dc4c92`.
>
> Test paths are given at their current location. Two suites moved after
> these runs: `ci-artifact-contract.test.ts` from `tests/unit/` to
> `tests/system/ci-runner/`, and `provider-guardian-transaction.test.ts` from
> `tests/unit/` to `tests/integration/`. Three suites were split on
> 2026-09-18 (`5cc41467`, `ec7f20e2`) and the third re-review rows follow the
> tests that moved: TR-02 to `presigned-transfer-delivery.test.ts`, TR-03's
> image probe to `image-cdn-browser-probe.test.ts`, TR-04 to
> `resumable-upload-runtime-teardown.test.ts` (all in `tests/unit/`). The run
> commands in the earlier sections keep the file each run used.
> 테스트 경로는 지금 위치로 적는다. 이 실행들 뒤에 테스트 파일 두 개가 옮겨졌다.
> `ci-artifact-contract.test.ts`는 `tests/unit/`에서 `tests/system/ci-runner/`로, `provider-guardian-transaction.test.ts`는 `tests/unit/`에서 `tests/integration/`로 옮겼다.
> 2026-09-18(`5cc41467`, `ec7f20e2`)에 테스트 파일 세 개를 나눴고, 세 번째 재검토의 행은 옮겨 간 테스트를 따른다.
> TR-02는 `presigned-transfer-delivery.test.ts`로, TR-03의 image probe는 `image-cdn-browser-probe.test.ts`로, TR-04는 `resumable-upload-runtime-teardown.test.ts`로 갔다(모두 `tests/unit/` 안).
> 앞 절들의 실행 명령은 그 실행이 쓴 파일을 그대로 적는다.
## Containment state (plan Task 1, Step 1)
## 격리 상태 (계획 Task 1, Step 1)
Scan performed on the baseline revision:
기준 리비전에서 돌린 검색:
```bash
rg -n "createBrowserOpfsRuntime|createBrowserFileRuntime|createPublicResponseCache|createBrowserRpcRuntime|createWebPush|createServiceWorker|createResumableUpload|createImageCdn" src recipes tests
rg -n "AVAILABLE_NOT_COMPOSED|DESIGNED_NOT_IMPLEMENTED|NOT_SELECTED" docs/architecture src/bootstrap
```
Result:
결과:
| Capability | Template default composition | Containment action |
| Capability | 템플릿 기본 조립 여부 | 격리(containment) 조치 |
| --- | --- | --- |
| OPFS byte store (`createBrowserOpfsRuntime`) | Not composed. Only `recipes/frontend-capabilities/*` reference the `"OPFS"` backend literal in contract/fake code. | None required. No V1 writer is admitted, so no kill switch is invented. |
| Browser files runtime | Not composed in `src/bootstrap/**`. | None. |
| Public response cache | Not composed; only `tests/unit/public-response-cache.test.ts` constructs it. | None. |
| Browser RPC runtime | Not composed; `AVAILABLE_NOT_COMPOSED`. | None. |
| Web Push | Not composed; `NOT_SELECTED` / `AVAILABLE_NOT_COMPOSED`. | None. |
| Resumable upload / image CDN | Not composed; test-only construction. | None. |
| Service Worker runtime host | Composed conditionally through `src/bootstrap/optional-runtime-host.ts` → `createServiceWorkerRuntimeHost`, gated by `ResolvedRuntimeCapabilities`. | Stays as-is. Task 14 fixes truthfulness without changing selection. |
| Realtime | `src/bootstrap/optional-runtime-host.ts:91` keeps realtime `NOT_SELECTED` with `realtime: null`. | None. |
| OPFS 바이트 저장소 (`createBrowserOpfsRuntime`) | 조립하지 않는다. `recipes/frontend-capabilities/*`만 contract/fake 코드에서 `"OPFS"` backend 리터럴을 참조한다. | 필요 없다. V1 writer를 받아들이지 않으므로 kill switch를 새로 만들지 않는다. |
| 브라우저 파일 runtime | `src/bootstrap/**`에서 조립하지 않는다. | 없음. |
| 공개 응답 캐시 | 조립하지 않는다. `tests/unit/public-response-cache.test.ts`만 이것을 만든다. | 없음. |
| Browser RPC runtime | 조립하지 않는다. `AVAILABLE_NOT_COMPOSED`. | 없음. |
| Web Push | 조립하지 않는다. `NOT_SELECTED` / `AVAILABLE_NOT_COMPOSED`. | 없음. |
| 재개 가능 업로드(resumable upload) / image CDN | 조립하지 않는다. 테스트에서만 만든다. | 없음. |
| Service Worker runtime host | `src/bootstrap/optional-runtime-host.ts` → `createServiceWorkerRuntimeHost`로 조건부 조립한다. `ResolvedRuntimeCapabilities`가 켜고 끈다. | 그대로 둔다. Task 14가 선택은 바꾸지 않고, 보고 값이 사실과 맞도록 고친다. |
| Realtime | `src/bootstrap/optional-runtime-host.ts:91`이 realtime을 `realtime: null`로 두고 `NOT_SELECTED`로 유지한다. | 없음. |
No product-specific composition root outside the template default exists in this repository, so
there is no OPFS V1 write admission to close.
이 저장소에는 템플릿 기본 말고 제품 전용 composition root가 없다. 그래서 막아야 할 OPFS V1 쓰기 허용 경로도 없다.
## Baseline gates (plan Task 1, Step 3)
## 기준 게이트 (계획 Task 1, Step 3)
Captured on the baseline revision before any source change.
소스를 바꾸기 전에 기준 리비전에서 기록했다.
| Command | Exit code | Result |
| 명령 | 종료 코드 | 결과 |
| --- | ---: | --- |
| `corepack pnpm check:types` | 0 | app, node, test, recipes, web-worker, service-worker projects all pass. |
| `corepack pnpm lint` | 0 | `--max-warnings=0` clean. |
| `corepack pnpm check:architecture` | 0 | 286 modules, 854 dependencies, all imports resolved; 12 graph fixtures PASS; TS-only policy PASS; allowed PASS / 9 forbidden rejected. |
| `corepack pnpm test:unit` | 1 | 110 passed / 1 failed test files; 1496 passed / 19 failed tests (1515 total), 150.92s. |
| `corepack pnpm check:types` | 0 | app, node, test, recipes, web-worker, service-worker 프로젝트가 모두 통과한다. |
| `corepack pnpm lint` | 0 | `--max-warnings=0`로 경고 없음. |
| `corepack pnpm check:architecture` | 0 | 모듈 286개, 의존 854개, import 해석 실패 없음. graph fixture 12개 PASS. TS-only 정책 PASS. 허용 PASS / 금지 9개 거부. |
| `corepack pnpm test:unit` | 1 | 테스트 파일 110개 통과 / 1개 실패. 테스트 1496개 통과 / 19개 실패(전체 1515개), 150.92s. |
### `test:unit` failure attribution
### `test:unit` 실패 원인
The single failing file is `tests/system/ci-runner/ci-artifact-contract.test.ts`. All 19 failures come from
child-process, cgroup, and filesystem-permission behavior of the sandboxed execution
environment, not from adapter code. Verbatim causes recorded from the run log:
실패하는 파일은 `tests/system/ci-runner/ci-artifact-contract.test.ts` 하나다. 실패 19건은 모두 sandbox 실행 환경의 자식 프로세스, cgroup, 파일 시스템 권한 동작에서 나왔다. adapter 코드 탓이 아니다. 실행 로그에서 기록한 원인 원문:
```
Error: ENOENT: no such file or directory, open '/proc/1325422/task/1325422/children'
@@ -69,468 +60,398 @@ AssertionError: expected 5714 to be less than 5000
AssertionError: expected [] to deeply equal ArrayContaining{…}
```
This matches the environment note already recorded in the review index. It is **not** converted
to an adapter failure and it is **not** treated as green. Every adapter task below must keep the
adapter-focused suites green and must not increase this file's failure count.
리뷰 색인에 이미 적힌 환경 메모와 같다. adapter 실패로 바꾸지 **않고**, 통과(green)로도 보지 **않는다**. 아래의 모든 adapter 작업은 adapter 중심 테스트 파일을 통과 상태로 유지해야 하고, 이 파일의 실패 수를 늘리면 안 된다.
## Finding ledger
## 발견 원장
`Activation` records whether the finding is reachable on the current template execution path.
Rollout state starts at `NOT_STARTED`; documented-unimplemented items start at
`PROMOTION_BLOCKED` and are never labelled `DEFECT`.
`Activation` 열은 그 발견이 지금 템플릿 실행 경로에서 닿는지(활성화 여부)를 적는다. Rollout 상태는 `NOT_STARTED`에서 시작한다. 문서에 미구현으로 적힌 항목은 `PROMOTION_BLOCKED`에서 시작하고, `DEFECT`로 표시하지 않는다.
### Network and state (`docs/reviews/adapters/01-network-and-state.md`)
### 네트워크와 상태 (`docs/reviews/adapters/01-network-and-state.md`)
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
| ID | Activation | 실패 테스트(red test) 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
| --- | --- | --- | --- | --- | --- | --- |
| N-01 | Live V3 path | `corepack pnpm exec vitest run tests/integration/http-execution-v3-observability.test.ts` | `fix: restore V3 HTTP observability` | `FIXED_NOT_RELEASED` | diagnostics/telemetry producer gate regression | Red 5/5 failed → green 5/5; `check:diagnostics` PASS (8 diagnostics, 5 telemetry producers); `check:types` PASS; `check:architecture` PASS |
| N-02 | Live V3 path | `corepack pnpm exec vitest run tests/integration/http-execution-v3-auth-profile.test.ts` | `fix: enforce installed HTTP auth profiles` | `FIXED_NOT_RELEASED` | authenticated request 4xx spike after profile enforcement | Red suite failed to load (`installRestAuthProfileRegistry` absent) → green 7/7; `check:types` PASS; `check:architecture` PASS; `lint` PASS; unit+integration+features 1560 passed with only the pre-existing environmental `ci-artifact-contract` failures |
| N-03 | Live V3 path | `corepack pnpm exec vitest run tests/unit/http-execution-v3.test.ts -t "retry-time fence"` | `fix: preserve command effect certainty across retries` | `FIXED_NOT_RELEASED` | command effect verdict regression | Red reproduced `SCOPE_FENCED` with `NOT_STARTED` after one dispatched attempt → green `MAYBE_APPLIED`; lattice table 9/9; `check:types` PASS; `lint` PASS |
| N-04 | Live composition teardown | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts tests/unit/runtime-adapters.test.ts` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | telemetry delivery loss after teardown change | Red 10 failed (5 lifecycle + 5 capacity) → green 34/34; `check:diagnostics` PASS; `check:types` PASS; `check:architecture` PASS; `lint` PASS |
| N-05 | Rollout blocker (sidecar not composed) | `corepack pnpm exec vitest run tests/unit/conditional-validator-store.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | persisted validator key incompatibility | Red collision case (two valid bindings sharing one delimiter-joined key) → green; key is now a bounded validated tuple encoded with `JSON.stringify` |
| N-06 | Legacy V2 rollback seam | The V2 client test tests/integration/http-client.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy keyed command rejection spike | Red 4 invalid-key cases → green; rejection happens before credentials and fetch (0 credential calls, 0 fetches) |
| N-07 | Legacy V2 rollback seam | The V2 client tests tests/integration/http-client.test.ts and tests/integration/auth-recovery.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy credential timeout regression | Red never-settling owner → green; credential wait races the existing attempt controller so no extra timer is added; ownership maps to REQUEST_TIMEOUT / REQUEST_ABORTED / AUTH_INTEGRATION_FAILURE with zero fetches |
| N-08 | Legacy V2 rollback seam | The V2 bounded JSON test tests/unit/bounded-json-compatibility.test.ts (deleted with the V2 client on 2026-11-03) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | legacy JSON failure-code drift | Green 7/7 including throwing cancel/releaseLock; `readBoundedJson` now delegates to `bounded-body-reader` with the legacy codes preserved |
| N-09 | Live cross-context host | `corepack pnpm exec vitest run tests/unit/cross-tab-invalidation.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | cross-tab invalidation drop | Red foreign-area pulse accepted → green 13/13; localStorage captured once and `StorageEvent.storageArea` compared by object identity; pulse key registered as `CACHE_INVALIDATION_PULSE`; `check:registries` PASS |
| N-10 | Cursor runtime `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/cursor-pagination-runtime.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | pagination abort semantics change | Red never-settling loader → green `PAGINATION_ABORTED` with the late page ignored |
| N-11 | Live composition | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts -t capacity` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | capacity rejection on valid composition | Red 5/5 capacity cases → green; ceilings documented in VD-07 §7-4 |
| N-01 | 실행 중인 V3 경로 | `corepack pnpm exec vitest run tests/integration/http-execution-v3-observability.test.ts` | `fix: restore V3 HTTP observability` | `FIXED_NOT_RELEASED` | diagnostics/telemetry producer 게이트 회귀 | 실패 5/5 → 통과 5/5. `check:diagnostics` PASS(diagnostic 8개, telemetry producer 5개). `check:types` PASS. `check:architecture` PASS |
| N-02 | 실행 중인 V3 경로 | `corepack pnpm exec vitest run tests/integration/http-execution-v3-auth-profile.test.ts` | `fix: enforce installed HTTP auth profiles` | `FIXED_NOT_RELEASED` | profile 강제 뒤 인증 요청 4xx 급증 | 실패: 테스트 파일이 로드되지 않음(`installRestAuthProfileRegistry` 없음) → 통과 7/7. `check:types` PASS. `check:architecture` PASS. `lint` PASS. unit+integration+features 1560개 통과, 실패는 원래 있던 환경 탓 `ci-artifact-contract` 실패뿐 |
| N-03 | 실행 중인 V3 경로 | `corepack pnpm exec vitest run tests/unit/http-execution-v3.test.ts -t "retry-time fence"` | `fix: preserve command effect certainty across retries` | `FIXED_NOT_RELEASED` | command effect 판정 회귀 | 실패: 시도 한 번을 보낸 뒤 `NOT_STARTED`와 함께 `SCOPE_FENCED`가 재현됨 → 통과 `MAYBE_APPLIED`. lattice 표 9/9. `check:types` PASS. `lint` PASS |
| N-04 | 실행 중인 조립의 정리(teardown) | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts tests/unit/runtime-adapters.test.ts` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | teardown 변경 뒤 telemetry 전달 유실 | 실패 10개(lifecycle 5 + capacity 5) → 통과 34/34. `check:diagnostics` PASS. `check:types` PASS. `check:architecture` PASS. `lint` PASS |
| N-05 | Rollout 차단 요인(sidecar 조립 안 됨) | `corepack pnpm exec vitest run tests/unit/conditional-validator-store.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | 저장된 validator 키 비호환 | 실패: 충돌 사례(올바른 binding 두 개가 구분자로 이은 키 하나를 공유) → 통과. 키는 이제 크기가 제한되고 검증된 tuple이며 `JSON.stringify`로 인코딩한다 |
| N-06 | 구 V2 rollback 경계(seam) | V2 client 테스트 tests/integration/http-client.test.ts(2026-11-03에 V2 client와 함께 지웠다) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | 구 keyed command 거부 급증 | 실패: 잘못된 키 사례 4개 → 통과. credential과 fetch 전에 거부한다(credential 호출 0회, fetch 0회) |
| N-07 | 구 V2 rollback 경계(seam) | V2 client 테스트 tests/integration/http-client.test.ts와 tests/integration/auth-recovery.test.ts(2026-11-03에 V2 client와 함께 지웠다) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | 구 credential timeout 회귀 | 실패: 끝나지 않는 owner → 통과. credential 대기가 기존 attempt controller와 경주(race)하므로 타이머를 더 만들지 않는다. 소유권은 fetch 0회로 REQUEST_TIMEOUT / REQUEST_ABORTED / AUTH_INTEGRATION_FAILURE에 대응한다 |
| N-08 | 구 V2 rollback 경계(seam) | V2 bounded JSON 테스트 tests/unit/bounded-json-compatibility.test.ts(2026-11-03에 V2 client와 함께 지웠다) | `fix: harden the legacy HTTP rollback path` | `FIXED_NOT_RELEASED` | 구 JSON 실패 코드 drift | 통과 7/7(예외를 던지는 cancel/releaseLock 포함). `readBoundedJson`은 이제 구 코드를 그대로 두고 `bounded-body-reader`에 맡긴다 |
| N-09 | 실행 중인 cross-context host | `corepack pnpm exec vitest run tests/unit/cross-tab-invalidation.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | cross-tab 무효화 유실 | 실패: 다른 영역의 pulse를 받아들임 → 통과 13/13. localStorage를 한 번만 잡고 `StorageEvent.storageArea`를 객체 동일성으로 비교한다. pulse 키는 `CACHE_INVALIDATION_PULSE`로 등록했다. `check:registries` PASS |
| N-10 | Cursor runtime `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/cursor-pagination-runtime.test.ts` | `fix: harden bounded state sidecars` | `FIXED_NOT_RELEASED` | pagination abort 의미 변경 | 실패: 끝나지 않는 loader → 통과 `PAGINATION_ABORTED`, 늦게 온 page는 무시 |
| N-11 | 실행 중인 조립 | `corepack pnpm exec vitest run tests/unit/telemetry.test.ts -t capacity` | `fix: terminate telemetry work on disposal` | `FIXED_NOT_RELEASED` | 올바른 조립에서 capacity 거부 | 실패: capacity 사례 5/5 → 통과. 상한은 VD-07 §7-4에 적었다 |
### Storage and browser files (`docs/reviews/adapters/03-storage-and-browser-files.md`)
### 스토리지와 브라우저 파일 (`docs/reviews/adapters/03-storage-and-browser-files.md`)
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
| ID | Activation | 실패 테스트 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
| --- | --- | --- | --- | --- | --- | --- |
| STO-01 | OPFS not composed in template; **Critical** for any product writer | `corepack pnpm exec vitest run tests/unit/opfs-byte-store.test.ts tests/unit/opfs-worker-runtime.test.ts tests/unit/indexeddb-opfs-journal.test.ts` | `fix: preserve OPFS recovery authority during cleanup` | `FIXED_NOT_RELEASED` | OPFS reconcile backlog or journal growth | Red 4 new saga cases → green 25/25 across the three OPFS suites; `check:types` PASS (incl. web-worker); `check:browser-file-storage-boundaries` PASS; `lint` PASS; `test:unit` 1511 passed with only the pre-existing environmental `ci-artifact-contract` failures |
| STO-02 | Browser file runtime not composed | `corepack pnpm exec vitest run tests/unit/browser-file-download.test.ts` | `fix: execute canonical browser download targets` | `FIXED_NOT_RELEASED` | download navigation blocked by canonical target | Red 2 failed (raw relative href handed to host) → green 17/17 |
| STO-03 | Public cache not composed | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | composition rejection of an existing policy | Red 4 cases across STO-03..05 → green 21/21; `check:types` PASS; `check:browser-file-storage-boundaries` PASS; `lint` PASS |
| STO-04 | Public cache not composed | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | restage loop or bandwidth spike | — |
| STO-05 | Public cache not composed | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | activation permitted without required capability | — |
| STO-06 | IndexedDB maintenance | `corepack pnpm exec vitest run tests/unit/indexeddb-maintenance.test.ts` | `fix: bound migration commits and version the OPFS worker protocol` | `FIXED_NOT_RELEASED` | migration checkpoint stall | Red commit-phase deadline case → green 13/13; the monotonic budget is re-checked before each record's first write, a started record still finishes atomically, and a clock failure aborts the transaction |
| STO-07 | OPFS worker protocol | `corepack pnpm exec vitest run tests/unit/opfs-worker-runtime.test.ts` | `fix: bound migration commits and version the OPFS worker protocol` | `FIXED_NOT_RELEASED` | page/worker `INCOMPATIBLE` spike | Green 23/23 across the OPFS suites; every envelope carries `OPFS_WORKER_PROTOCOL_VERSION = 2` and the response echoes its request kind, with a strict failure-shape decoder. A kind or version mismatch closes as `UNSUPPORTED` — the closed taxonomy has no `INCOMPATIBLE` code and none was invented |
| STO-08 | Hypothesis; browser characterization required | `corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/browser-files.spec.ts` | none (source unchanged) | `UNVERIFIED` | n/a until characterized | chromium 2/2 PASS; webkit could not launch (`libevent-2.1-7t64`, `libavif16` missing — environmental). The existing spec does not exercise `Window.showOpenFilePicker`/`showSaveFilePicker`, which need a user gesture and a native dialog, so the receiver-binding hypothesis is **neither reproduced nor refuted**. No `SystemPickerHost` was introduced: the plan forbids implementing an uncharacterized hypothesis as a defect. |
| GAP-01 | Documented unimplemented (VD-15) | promotion evidence, not a red test | — | `PROMOTION_BLOCKED` | n/a | — |
| GAP-02 | Documented unimplemented (VD-15) | promotion evidence, not a red test | — | `PROMOTION_BLOCKED` | n/a | — |
| GAP-03 | Documented unimplemented (VD-15) | promotion evidence, not a red test | — | `PROMOTION_BLOCKED` | n/a | — |
| STO-01 | 템플릿에서 OPFS 조립 안 됨. 제품 writer가 있으면 **Critical** | `corepack pnpm exec vitest run tests/unit/opfs-byte-store.test.ts tests/unit/opfs-worker-runtime.test.ts tests/unit/indexeddb-opfs-journal.test.ts` | `fix: preserve OPFS recovery authority during cleanup` | `FIXED_NOT_RELEASED` | OPFS reconcile 적체 또는 journal 증가 | 실패: 새 saga 사례 4개 → OPFS 테스트 파일 3개에서 통과 25/25. `check:types` PASS(web-worker 포함). `check:browser-file-storage-boundaries` PASS. `lint` PASS. `test:unit` 1511개 통과, 실패는 원래 있던 환경 탓 `ci-artifact-contract` 실패뿐 |
| STO-02 | 브라우저 파일 runtime 조립 안 됨 | `corepack pnpm exec vitest run tests/unit/browser-file-download.test.ts` | `fix: execute canonical browser download targets` | `FIXED_NOT_RELEASED` | canonical target 때문에 다운로드 이동이 막힘 | 실패 2개(가공하지 않은 상대 href를 host에 넘김) → 통과 17/17 |
| STO-03 | 공개 캐시 조립 안 됨 | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | 기존 정책을 조립 단계에서 거부 | 실패: STO-03..05에 걸친 사례 4개 → 통과 21/21. `check:types` PASS. `check:browser-file-storage-boundaries` PASS. `lint` PASS |
| STO-04 | 공개 캐시 조립 안 됨 | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | restage 반복 또는 대역폭 급증 | — |
| STO-05 | 공개 캐시 조립 안 됨 | `corepack pnpm exec vitest run tests/unit/public-response-cache.test.ts` | `fix: make public cache staging repairable` | `FIXED_NOT_RELEASED` | 필요한 capability 없이 활성화 허용 | — |
| STO-06 | IndexedDB 유지보수 | `corepack pnpm exec vitest run tests/unit/indexeddb-maintenance.test.ts` | `fix: bound migration commits and version the OPFS worker protocol` | `FIXED_NOT_RELEASED` | migration checkpoint 멈춤 | 실패: commit 단계 deadline 사례 → 통과 13/13. 단조(monotonic) budget을 각 레코드의 첫 쓰기 전에 다시 확인한다. 이미 시작한 레코드는 원자적으로 끝낸다. clock이 실패하면 transaction을 중단한다 |
| STO-07 | OPFS worker 프로토콜 | `corepack pnpm exec vitest run tests/unit/opfs-worker-runtime.test.ts` | `fix: bound migration commits and version the OPFS worker protocol` | `FIXED_NOT_RELEASED` | page/worker `INCOMPATIBLE` 급증 | OPFS 테스트 파일에서 통과 23/23. 모든 envelope가 `OPFS_WORKER_PROTOCOL_VERSION = 2`를 담고, 응답은 요청 kind를 그대로 돌려준다. 실패 모양은 엄격한 decoder로 읽는다. kind나 버전이 다르면 `UNSUPPORTED`로 닫는다. 닫힌 분류(closed taxonomy)에는 `INCOMPATIBLE` 코드가 없고, 새로 만들지도 않았다 |
| STO-08 | 가설. 브라우저에서 동작 확인(characterization)이 필요 | `corepack pnpm exec playwright test --config playwright.capabilities.config.ts tests/browser-capabilities/browser-files.spec.ts` | 없음(소스 바꾸지 않음) | `UNVERIFIED` | 확인 전까지 해당 없음 | chromium 2/2 PASS. webkit은 실행되지 않았다(`libevent-2.1-7t64`, `libavif16` 없음, 환경 문제). 기존 spec은 `Window.showOpenFilePicker`/`showSaveFilePicker`를 실행하지 않는다. 이 둘은 사용자 동작과 네이티브 대화상자가 필요하다. 그래서 receiver-binding 가설은 **재현하지도 반박하지도 못했다**. `SystemPickerHost`는 만들지 않았다. 계획은 확인하지 않은 가설을 결함으로 보고 구현하는 것을 금한다. |
| GAP-01 | 문서에 미구현으로 적힘(VD-15) | promotion 증거(실패 테스트가 아님) | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
| GAP-02 | 문서에 미구현으로 적힘(VD-15) | promotion 증거(실패 테스트가 아님) | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
| GAP-03 | 문서에 미구현으로 적힘(VD-15) | promotion 증거(실패 테스트가 아님) | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
### Realtime and Browser RPC (`docs/reviews/adapters/02-realtime-and-browser-rpc.md`)
### Realtime과 Browser RPC (`docs/reviews/adapters/02-realtime-and-browser-rpc.md`)
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
| ID | Activation | 실패 테스트 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
| --- | --- | --- | --- | --- | --- | --- |
| R-01 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-runtime.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | stream lease deadlock | Stream cleanup is bounded; the generator no longer waits indefinitely on a non-cooperative `iterator.return()` |
| R-02 | Realtime `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/realtime/stream-coordinator.test.ts` | `fix: retain realtime work through draining` | `FIXED_NOT_RELEASED` | stream stuck in `DRAINING` | Red never-settling effect and recovery → green 27/27; `close()` returns `IDLE_TIMEOUT` while a task is retained and success only after actual settlement |
| R-03 | Realtime `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/realtime/live-poll-handoff-coordinator.test.ts` | `fix: retain realtime work through draining` | `FIXED_NOT_RELEASED` | retired-writer set growth | Red overflow fail-close then `close()` → green 11/11; retired writers are waited on and only removed once actually quiesced |
| R-04 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-contract.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | binding install rejection | Red post-validation mutation, accessor and symbol cases → green 19/19; getters are never invoked |
| R-05 | WebSocket protocol codec | `corepack pnpm exec vitest run tests/unit/realtime/websocket-protocol.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | frame rejection regression | Red oversize frame allocated an encoder copy → green 8/8; byte counts match `TextEncoder` including lone surrogates |
| R-06 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-runtime.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | closed-failure taxonomy drift | Clock and fence reads are canonicalised into the closed Result taxonomy with single-exit cleanup |
| R-07 | Promotion blocker | concrete transport conformance evidence | — | `PROMOTION_BLOCKED` | n/a | — |
| R-01 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-runtime.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | stream lease 교착 | stream 정리에 시간 제한이 있다. generator는 협조하지 않는 `iterator.return()`을 더는 끝없이 기다리지 않는다 |
| R-02 | Realtime `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/realtime/stream-coordinator.test.ts` | `fix: retain realtime work through draining` | `FIXED_NOT_RELEASED` | stream이 `DRAINING`에 멈춤 | 실패: 끝나지 않는 effect와 recovery → 통과 27/27. 작업이 남아 있는 동안 `close()`는 `IDLE_TIMEOUT`을 돌려주고, 실제로 끝난 뒤에만 성공을 돌려준다 |
| R-03 | Realtime `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/realtime/live-poll-handoff-coordinator.test.ts` | `fix: retain realtime work through draining` | `FIXED_NOT_RELEASED` | retired writer 집합 증가 | 실패: overflow로 fail-close한 뒤 `close()` → 통과 11/11. retired writer를 기다리고, 실제로 멈춘 뒤에만 지운다 |
| R-04 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-contract.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | binding 설치 거부 | 실패: 검증 뒤 변경, accessor, symbol 사례 → 통과 19/19. getter를 한 번도 부르지 않는다 |
| R-05 | WebSocket 프로토콜 codec | `corepack pnpm exec vitest run tests/unit/realtime/websocket-protocol.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | frame 거부 회귀 | 실패: 너무 큰 frame이 encoder 사본을 할당함 → 통과 8/8. 바이트 수가 짝 없는 surrogate까지 포함해 `TextEncoder`와 같다 |
| R-06 | Browser RPC `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/browser-rpc/browser-rpc-runtime.test.ts` | `fix: install bounded Browser RPC stream leases` | `FIXED_NOT_RELEASED` | 닫힌 실패 분류 drift | clock과 fence 읽기 결과를 닫힌 Result 분류로 정규화하고, 정리는 출구 하나에서 한다 |
| R-07 | Promotion 차단 요인 | 실제 transport 적합성 증거 | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
### Browser transfer (`docs/reviews/adapters/04-browser-transfer.md`)
### 브라우저 전송 (`docs/reviews/adapters/04-browser-transfer.md`)
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
| ID | Activation | 실패 테스트 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
| --- | --- | --- | --- | --- | --- | --- |
| BT-PRE-01 | Presigned `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: lazy presigned download leases` | `FIXED_NOT_RELEASED` | download lease leak | Red lazy-lease cases → green 29/29; `open()` performs no network I/O and `close()` is idempotent |
| BT-PRE-02 | Wire contract gap | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | provider `POLICY_REJECTED` spike | Red missing/V0/V2 protocol cases → green; request always declares `PRESIGNED_TRANSFER_V1` and a mismatched response is closed as `POLICY_REJECTED` before vault registration |
| BT-PRE-03 | Presigned provider | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | timeout not bounding fetch | Red non-cooperative fetch → green; the scope races the task, the late response body is cancelled, and a throwing scheduler leaks no listener |
| BT-PRE-04 | Presigned vault | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | issuer/consumer split break | Red 6-case issuer-seam table → green; the vault re-checks method, href/origin/path agreement, credentials, byte, digest and expiry invariants itself |
| BT-PRE-05 | Provider path decoding | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | legitimate key rejection | Red `%2F`, `%5C`, `%252e%252e`, lowercase percent-hex and `%00` → green; each segment is decoded once and must round-trip through the canonical uppercase encoder |
| BT-UP-01 | Resumable transport | `corepack pnpm exec vitest run tests/unit/resumable-upload-fetch-transport.test.ts` | `fix: harden resumable upload transport contracts` | `FIXED_NOT_RELEASED` | signal facade rejection | `isAbortSignal` now requires `removeEventListener` and release cleanup is isolated |
| BT-UP-02 | Resumable transport | `corepack pnpm exec vitest run tests/unit/resumable-upload-fetch-transport.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | clock injection break | Clock and scheduler are injected and snapshotted; delta-seconds and HTTP-date both resolve against the same captured `now`, with clock rollback clamped to 0 |
| BT-UP-03 | Resumable checkpoint store | `corepack pnpm exec vitest run tests/unit/resumable-upload-checkpoint.test.ts` | `fix: report unknown IndexedDB delete effects` | `FIXED_NOT_RELEASED` | pending-delete registry growth | Red blocked-deadline case → green `PENDING`/`UNKNOWN`; a realm-scoped registry blocks recreating the partition |
| BT-UP-04 | Presigned part executor | `corepack pnpm exec vitest run tests/unit/resumable-upload-checkpoint.test.ts` | `fix: harden resumable upload transport contracts` | `FIXED_NOT_RELEASED` | expiry check rejection | Non-finite and negative clocks return `UNAVAILABLE`/`RESUME` instead of bypassing expiry |
| BT-UP-05 | Refactor | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | — | `NOT_PERFORMED` | characterization drift | **Attempted and reverted.** The five internal owners were extracted mechanically, but they require a shared-internals module for `RuntimeDependencies`, `ActiveResolution`, `ReconciliationResolution`, `FAILURE_CODES`, `RECOVERIES`, `reportProgress`, `observeTerminal` and ~40 further bindings to avoid an import cycle. Rather than risk the verified correctness work in this file, the extraction was reverted rather than half-landed. Behaviour and the public facade are unchanged; the file is still 2,239 lines. |
| BT-UP-06 | Refactor | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | `fix: drain resumable upload teardown` | `FIXED_NOT_RELEASED` | drain not quiescent | Red single-flight dispose case → green 18/18; `close()` closes admission and starts the same drain, `dispose()` aborts the active-operation registry and awaits real settlement before closing the checkpoint store |
| BT-UP-07 | Documented gap (Web Locks matrix) | promotion evidence | — | `PROMOTION_BLOCKED` | n/a | — |
| BT-IMG-01 | Type-contract change | `corepack pnpm check:types:test` fixture | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | caller compile break | `resolve()` now requires the lifetime signal; `tests/fixtures/typecheck/invalid-image-cdn-resolve-signal.ts` + `check:types:fixture:image-resolve-signal` fail as designed (2 errors), and all callers pass a signal |
| BT-IMG-02 | Image probe | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | `fix: parse Cache-Control with quote awareness` | `FIXED_NOT_RELEASED` | Cache-Control parse rejection | Red unmatched-quote cases → green 25/25 |
| BT-IMG-03 | Refactor | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | — | `NOT_PERFORMED` | characterization drift | **Not performed.** Same reasoning as BT-UP-05: a pure cohesion refactor of `image-cdn-runtime.ts` (1,340 lines) with no finding closure. `image-header-metadata.ts` is deliberately left intact per the review. |
| BT-IMG-04 | Documented gap (descriptor provider) | promotion evidence | — | `PROMOTION_BLOCKED` | n/a | — |
| BT-X-01 | Shared abort mechanics | `corepack pnpm exec vitest run tests/unit/abortable-operation.test.ts` | `fix: share abort and deadline mechanics` | `FIXED_NOT_RELEASED` | late-result compensation regression | Golden suite 8/8: first terminal owner, idempotent close, throwing scheduler, observed late rejection, late-handle compensation |
| BT-PRE-01 | Presigned `AVAILABLE_NOT_COMPOSED` | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: lazy presigned download leases` | `FIXED_NOT_RELEASED` | 다운로드 lease 누수 | 실패: lazy lease 사례 → 통과 29/29. `open()`은 네트워크 I/O를 하지 않고, `close()`는 여러 번 불러도 결과가 같다(idempotent) |
| BT-PRE-02 | wire 계약 빈틈 | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | provider `POLICY_REJECTED` 급증 | 실패: protocol 없음/V0/V2 사례 → 통과. 요청은 늘 `PRESIGNED_TRANSFER_V1`을 선언하고, 맞지 않는 응답은 vault에 등록하기 전에 `POLICY_REJECTED`로 닫는다 |
| BT-PRE-03 | Presigned provider | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | timeout이 fetch를 끊지 못함 | 실패: 협조하지 않는 fetch → 통과. scope가 작업과 경주하고, 늦게 온 응답 body는 취소하며, 예외를 던지는 scheduler도 listener를 남기지 않는다 |
| BT-PRE-04 | Presigned vault | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | issuer/consumer 분리 깨짐 | 실패: issuer 경계 사례 6개 표 → 통과. vault가 method, href/origin/path 일치, credential, byte, digest, 만료 불변식을 직접 다시 확인한다 |
| BT-PRE-05 | Provider 경로 디코딩 | `corepack pnpm exec vitest run tests/unit/presigned-transfer.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | 정상 키 거부 | 실패: `%2F`, `%5C`, `%252e%252e`, 소문자 percent-hex, `%00` → 통과. 각 segment는 한 번만 디코딩하고, canonical 대문자 encoder로 다시 인코딩했을 때 원래 값과 같아야 한다 |
| BT-UP-01 | Resumable transport | `corepack pnpm exec vitest run tests/unit/resumable-upload-fetch-transport.test.ts` | `fix: harden resumable upload transport contracts` | `FIXED_NOT_RELEASED` | signal facade 거부 | `isAbortSignal`은 이제 `removeEventListener`를 요구하고, release 정리는 따로 격리했다 |
| BT-UP-02 | Resumable transport | `corepack pnpm exec vitest run tests/unit/resumable-upload-fetch-transport.test.ts` | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | clock 주입 깨짐 | clock과 scheduler를 주입받아 snapshot한다. delta-seconds와 HTTP-date 둘 다 같은 시점에 잡은 `now`로 계산하고, clock이 뒤로 가면 0으로 맞춘다 |
| BT-UP-03 | Resumable checkpoint store | `corepack pnpm exec vitest run tests/unit/resumable-upload-checkpoint.test.ts` | `fix: report unknown IndexedDB delete effects` | `FIXED_NOT_RELEASED` | pending-delete registry 증가 | 실패: deadline에 막힌 사례 → 통과 `PENDING`/`UNKNOWN`. realm 범위 registry가 partition을 다시 만들지 못하게 막는다 |
| BT-UP-04 | Presigned part executor | `corepack pnpm exec vitest run tests/unit/resumable-upload-checkpoint.test.ts` | `fix: harden resumable upload transport contracts` | `FIXED_NOT_RELEASED` | 만료 검사 거부 | 유한하지 않거나 음수인 clock은 만료 검사를 건너뛰지 않고 `UNAVAILABLE`/`RESUME`을 돌려준다 |
| BT-UP-05 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | — | `NOT_PERFORMED` | 동작 기록(characterization) drift | **시도했다가 되돌렸다.** 내부 owner 다섯 개는 기계적으로 뽑아냈다. 그러나 import 순환을 피하려면 `RuntimeDependencies`, `ActiveResolution`, `ReconciliationResolution`, `FAILURE_CODES`, `RECOVERIES`, `reportProgress`, `observeTerminal`과 바인딩 약 40개를 더 담은 공유 내부 모듈이 필요했다. 이 파일에서 검증한 정확성 작업을 위험에 빠뜨리지 않으려고, 반만 반영하지 않고 추출을 되돌렸다. 동작과 공개 facade는 그대로다. 파일은 여전히 2,239줄이다. |
| BT-UP-06 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/resumable-upload-runtime.test.ts` | `fix: drain resumable upload teardown` | `FIXED_NOT_RELEASED` | drain 뒤에도 작업이 남음 | 실패: single-flight dispose 사례 → 통과 18/18. `close()`는 새 작업 받기를 닫고 같은 drain을 시작한다. `dispose()`는 active-operation registry를 중단하고, 실제로 끝나기를 기다린 뒤 checkpoint store를 닫는다 |
| BT-UP-07 | 문서에 적힌 빈틈(Web Locks 매트릭스) | promotion 증거 | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
| BT-IMG-01 | 타입 계약 변경 | `corepack pnpm check:types:test` fixture | `fix: complete presigned capability and upload transport contracts` | `FIXED_NOT_RELEASED` | 호출부 컴파일 깨짐 | `resolve()`는 이제 lifetime signal을 요구한다. `tests/fixtures/typecheck/invalid-image-cdn-resolve-signal.ts` + `check:types:fixture:image-resolve-signal`은 설계대로 실패하고(오류 2개), 모든 호출부가 signal을 넘긴다 |
| BT-IMG-02 | Image probe | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | `fix: parse Cache-Control with quote awareness` | `FIXED_NOT_RELEASED` | Cache-Control 파싱 거부 | 실패: 짝 없는 따옴표 사례 → 통과 25/25 |
| BT-IMG-03 | 리팩터링 | `corepack pnpm exec vitest run tests/unit/image-cdn-runtime.test.ts` | — | `NOT_PERFORMED` | 동작 기록(characterization) drift | **하지 않았다.** BT-UP-05와 같은 이유다. `image-cdn-runtime.ts`(1,340줄)의 순수 응집도 리팩터링이고, 이것으로 닫히는 발견이 없다. `image-header-metadata.ts`는 리뷰에 따라 일부러 그대로 뒀다. |
| BT-IMG-04 | 문서에 적힌 빈틈(descriptor provider) | promotion 증거 | — | `PROMOTION_BLOCKED` | 해당 없음 | — |
| BT-X-01 | 공유 abort 메커니즘 | `corepack pnpm exec vitest run tests/unit/abortable-operation.test.ts` | `fix: share abort and deadline mechanics` | `FIXED_NOT_RELEASED` | 늦은 결과 보상 회귀 | 기준(golden) 테스트 8/8: 첫 terminal owner, idempotent close, 예외를 던지는 scheduler, 관찰된 늦은 rejection, 늦은 handle 보상 |
### Service Worker and Web Push (`docs/reviews/adapters/05-service-worker-and-web-push.md`)
### Service Worker와 Web Push (`docs/reviews/adapters/05-service-worker-and-web-push.md`)
| ID | Activation | Red test command | Fix commit/PR | Rollout state | Rollback trigger | Evidence |
| ID | Activation | 실패 테스트 명령 | 수정 커밋/PR | Rollout 상태 | Rollback 기준 | 증거 |
| --- | --- | --- | --- | --- | --- | --- |
| SW-URL-01 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | static asset cache miss rate | Red generator-shaped root-relative asset vs absolute Request URL → green; manifest URLs canonicalized once against the registration scope |
| SW-01 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | stale response served | Red previous-cache hit → green network fallback; only the current release cache is opened, matched and deleted from |
| SW-02 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | foreign cache deletion | Red prefix deletion of `ca-static-v1-not-owned` and longer suffixes → green exact `isOwnedStaticCacheName` only |
| SW-03 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | false removal success | Red `unregister() === false` reported as UNREGISTERED → green FAILED |
| SW-04 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | removal outcome misreport | Red removal modes always DISABLED → green outcome matrix (ABSENT/UNREGISTERED/PURGED→DISABLED, OWNERSHIP_MISMATCH→INCOMPATIBLE, FAILED→FAILED) |
| SW-05 | Build gate | `corepack pnpm exec vitest run tests/unit/service-worker-build-input.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | build admission rejection | Red tamper table (stale digest, byte length, cross-origin URL, dot segment, extension mismatch, unknown field, duplicate URL) → green; build gate decodes through the shared codec and recomputes the canonical digest |
| SW-06 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | activation handshake failure | Red foreign-source drain, source swap and 10 concurrent activations → green 24/24; replies correlate by source object identity against the captured waiting worker or controller, and activation/reset are single-flight |
| SW-07 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | activation blocked with zero clients | An empty in-scope client set is vacuously drained; `clients.matchAll()` failure still rejects |
| SW-08 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | per-client failure escalation | Per-client `postMessage` isolation; `skipWaiting()` is the commit point and its failure is REJECTED, with accepted/reload notifications sent only afterwards as best effort |
| SW-09 | Composed when capability selected | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | late install work observed | Red late-fetch case → green; a fenced worker starts no new candidate work, late response bodies are cancelled, digest throws map to a closed outcome, and a second exact-delete runs once the abandoned install settles without extending the public bound |
| SW-10 | Protocol V2 migration | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | — | `DEFERRED_TO_MIGRATION` | V1/V2 mismatch fail-close | Not closed here. Full-identity protocol V2 is an expand → dual-read → old-writer drain → contract deployment that spans releases; the prerequisite shared manifest codec and canonical digest landed with SW-05. |
| WP-01 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-fence-store.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | CAS receipt rejection | Red stale/skipped/huge revision receipts → green; write and remove share one exact-next-revision validator |
| WP-02 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-fence-store.test.ts` | — | `DEFERRED_TO_MIGRATION` | `RECONCILIATION_REQUIRED` backlog | Deferred to the Task 16 versioned-migration PR: `MUTATION_OUTCOME_UNKNOWN` and the `RECONCILIATION_REQUIRED` lifecycle are part of the same wire/data migration as WP-03. |
| WP-03 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | — | `DEFERRED_TO_MIGRATION` | backend receipt mismatch | Deferred to the Task 16 versioned-migration PR: the V2 receipt requires server request-shape negotiation before a client rollout. |
| WP-04 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | — | `DEFERRED_TO_MIGRATION` | reconcile loop | Deferred with WP-03: `expectedPreviousAssociationEpoch` and `replacedAssociationEpoch` are part of the V2 register contract. |
| WP-05 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | pre-abort observation drift | A pre-aborted command records the requested operation instead of always INSPECT |
| WP-06 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-worker-runtime.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | truncation reported degraded | Client handoff and notification cleanup report `countBucket` and `truncated`; an incomplete cleanup returns `{ complete: false }` and is DEGRADED |
| WP-07 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-worker-runtime.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | late native effect certainty | Native notification effect is tracked as NOT_APPLIED → MAYBE_APPLIED → CONFIRMED and observed as evidence only |
| SW-URL-01 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 정적 asset 캐시 miss 비율 | 실패: generator가 만든 root 기준 상대 asset과 절대 Request URL 비교 → 통과. manifest URL은 등록 scope 기준으로 한 번만 정규화한다 |
| SW-01 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 낡은 응답 제공 | 실패: 이전 캐시 hit → 통과: 네트워크 fallback. 지금 release 캐시만 열고, 찾고, 지운다 |
| SW-02 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 남의 캐시 삭제 | 실패: prefix로 `ca-static-v1-not-owned`와 더 긴 접미사까지 지움 → 통과: 정확한 `isOwnedStaticCacheName`만 |
| SW-03 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 거짓 제거 성공 | 실패: `unregister() === false`를 UNREGISTERED로 보고 → 통과: FAILED |
| SW-04 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 제거 결과 잘못 보고 | 실패: 제거 모드가 늘 DISABLED → 통과: 결과 매트릭스(ABSENT/UNREGISTERED/PURGED→DISABLED, OWNERSHIP_MISMATCH→INCOMPATIBLE, FAILED→FAILED) |
| SW-05 | 빌드 게이트 | `corepack pnpm exec vitest run tests/unit/service-worker-build-input.test.ts` | `fix: make Service Worker cache and removal outcomes truthful` | `FIXED_NOT_RELEASED` | 빌드 허용 거부 | 실패: 변조 사례 표(낡은 digest, 바이트 길이, cross-origin URL, dot segment, 확장자 불일치, 모르는 필드, 중복 URL) → 통과. 빌드 게이트는 공유 codec으로 디코딩하고 canonical digest를 다시 계산한다 |
| SW-06 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | activation handshake 실패 | 실패: 남의 source drain, source 바꿔치기, 동시 activation 10개 → 통과 24/24. 응답은 잡아 둔 waiting worker나 controller와 source 객체 동일성으로 맞춘다. activation/reset은 single-flight다 |
| SW-07 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | client 0개에서 activation 막힘 | scope 안 client 집합이 비어 있으면 drain된 것으로 본다. `clients.matchAll()` 실패는 여전히 거부한다 |
| SW-08 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | client별 실패가 전체로 번짐 | client별 `postMessage`를 격리한다. `skipWaiting()`이 commit 지점이고, 실패하면 REJECTED다. accepted/reload 알림은 그 뒤에만 best effort로 보낸다 |
| SW-09 | capability를 고르면 조립됨 | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | `fix: harden Service Worker activation and install lifecycle` | `FIXED_NOT_RELEASED` | 늦은 install 작업 관찰됨 | 실패: 늦은 fetch 사례 → 통과. fence된 worker는 새 후보 작업을 시작하지 않는다. 늦은 응답 body는 취소한다. digest 예외는 닫힌 결과로 대응한다. 버린 install이 끝나면 두 번째 exact-delete를 돌리되, 공개된 시간 한도를 늘리지 않는다 |
| SW-10 | 프로토콜 V2 migration | `corepack pnpm exec vitest run tests/unit/service-worker-runtime.test.ts` | — | `DEFERRED_TO_MIGRATION` | V1/V2 불일치 fail-close | 여기서 닫지 않았다. full-identity 프로토콜 V2는 expand → dual-read → old-writer drain → contract 순서의 배포이고, 여러 release에 걸친다. 선행 조건인 공유 manifest codec과 canonical digest는 SW-05와 함께 반영했다. |
| WP-01 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-fence-store.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | CAS receipt 거부 | 실패: 낡은/건너뛴/아주 큰 revision receipt → 통과. write와 remove가 exact-next-revision validator 하나를 같이 쓴다 |
| WP-02 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-fence-store.test.ts` | — | `DEFERRED_TO_MIGRATION` | `RECONCILIATION_REQUIRED` 적체 | Task 16 버전 migration PR로 미뤘다. `MUTATION_OUTCOME_UNKNOWN`과 `RECONCILIATION_REQUIRED` lifecycle은 WP-03과 같은 wire/data migration의 일부다. |
| WP-03 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | — | `DEFERRED_TO_MIGRATION` | backend receipt 불일치 | Task 16 버전 migration PR로 미뤘다. V2 receipt는 client rollout 전에 서버와 요청 모양을 협상해야 한다. |
| WP-04 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | — | `DEFERRED_TO_MIGRATION` | reconcile 반복 | WP-03과 함께 미뤘다. `expectedPreviousAssociationEpoch`와 `replacedAssociationEpoch`는 V2 register 계약의 일부다. |
| WP-05 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-subscription-adapter.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | 사전 abort 관찰 drift | 미리 abort된 command는 늘 INSPECT가 아니라 요청된 작업을 기록한다 |
| WP-06 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-worker-runtime.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | 잘림을 degraded로 보고 | client handoff와 알림 정리가 `countBucket`과 `truncated`를 보고한다. 끝나지 않은 정리는 `{ complete: false }`를 돌려주고 DEGRADED다 |
| WP-07 | Web Push `NOT_SELECTED` | `corepack pnpm exec vitest run tests/unit/web-push-worker-runtime.test.ts` | `fix: bind Web Push mutations to exact authority` | `FIXED_NOT_RELEASED` | 늦은 네이티브 effect의 확실성 | 네이티브 알림 effect를 NOT_APPLIED → MAYBE_APPLIED → CONFIRMED로 추적하고, 증거로만 관찰한다 |
## Final evidence (plan Task 18)
## 최종 증거 (계획 Task 18)
Captured after every correctness task landed.
정확성 작업이 다 반영된 뒤 기록했다.
### Focused subsystem suites (fresh processes)
### 하위 시스템별 테스트 (새 프로세스)
| Suite | Exit | Result |
| 테스트 | 종료 | 결과 |
| --- | ---: | --- |
| `tests/unit/browser-rpc` + `tests/unit/realtime` | 0 | 192 passed |
| OPFS, IndexedDB, public cache, download | 0 | 80 passed |
| abortable-operation, presigned, resumable, image CDN | 0 | 104 passed |
| Service Worker + Web Push | 0 | 66 passed |
| `tests/unit/browser-rpc` + `tests/unit/realtime` | 0 | 192개 통과 |
| OPFS, IndexedDB, 공개 캐시, 다운로드 | 0 | 80개 통과 |
| abortable-operation, presigned, 재개 가능 업로드, image CDN | 0 | 104개 통과 |
| Service Worker + Web Push | 0 | 66개 통과 |
### Repository gates
### 저장소 게이트
| Command | Exit | Result |
| 명령 | 종료 | 결과 |
| --- | ---: | --- |
| `corepack pnpm check:types` | 0 | all six projects pass |
| `corepack pnpm lint` | 0 | `--max-warnings=0` clean |
| `corepack pnpm check:architecture` | 0 | 288 modules, 865 dependencies; 12 fixtures PASS; allowed PASS / 9 forbidden rejected |
| `corepack pnpm check:diagnostics` | 0 | 8 diagnostics and 5 telemetry producers PASS |
| `corepack pnpm check:browser-file-storage-boundaries` | 0 | PASS, 34 rejections |
| `corepack pnpm check:types` | 0 | 여섯 프로젝트 모두 통과 |
| `corepack pnpm lint` | 0 | `--max-warnings=0`로 경고 없음 |
| `corepack pnpm check:architecture` | 0 | 모듈 288개, 의존 865개. fixture 12개 PASS. 허용 PASS / 금지 9개 거부 |
| `corepack pnpm check:diagnostics` | 0 | diagnostic 8개와 telemetry producer 5개 PASS |
| `corepack pnpm check:browser-file-storage-boundaries` | 0 | PASS, 거부 34건 |
| `corepack pnpm check:realtime-boundaries` | 0 | PASS |
| `git diff --check` | 0 | clean |
| `corepack pnpm test:component` | 0 | 126 passed |
| `corepack pnpm test:integration` | 0 | 52 passed |
| 참조 샘플 기능 시험(그 script는 2026-11-07 샘플과 함께 지웠다) | 0 | 26 passed |
| `corepack pnpm test:recipes` | 0 | 17 passed |
| `corepack pnpm test:unit` | 1 | 1585 passed / 19 failed tests; the 19 are the unchanged pre-existing `ci-artifact-contract` sandbox failures |
| `corepack pnpm check:registries` | 0 | 11 registries PASS |
| `git diff --check` | 0 | 문제 없음 |
| `corepack pnpm test:component` | 0 | 126개 통과 |
| `corepack pnpm test:integration` | 0 | 52개 통과 |
| 참조 샘플 기능 시험(그 script는 2026-11-07 샘플과 함께 지웠다) | 0 | 26개 통과 |
| `corepack pnpm test:recipes` | 0 | 17개 통과 |
| `corepack pnpm test:unit` | 1 | 테스트 1585개 통과 / 19개 실패. 19개는 원래 있던 그대로인 `ci-artifact-contract` sandbox 실패다 |
| `corepack pnpm check:registries` | 0 | registry 11개 PASS |
| `corepack pnpm verify:documentation` | 0 | PASS_SCOPED |
| `corepack pnpm check:types:fixture:image-resolve-signal` | 1 | **Expected non-zero.** Negative fixture proving `resolve()` now rejects a call without a lifetime signal (BT-IMG-01). |
| `corepack pnpm check:types:fixture:image-resolve-signal` | 1 | **0이 아닌 것이 정상이다.** `resolve()`가 이제 lifetime signal 없는 호출을 거부함을 보이는 음성 fixture다(BT-IMG-01). |
`test:all` stops at `test:unit`, so the later suites above were run directly.
`test:all`은 `test:unit`에서 멈춘다. 그래서 위의 나머지 테스트는 직접 돌렸다.
### Final disposition of all 64 findings
### 발견 64건 전체의 최종 처리
| State | Count |
| 상태 | 수 |
| --- | ---: |
| `FIXED_NOT_RELEASED` | 51 |
| `PROMOTION_BLOCKED` (unchanged by design) | 6 |
| `PROMOTION_BLOCKED`(설계상 그대로) | 6 |
| `DEFERRED_TO_MIGRATION` (`WP-02`, `WP-03`, `WP-04`, `SW-10`) | 4 |
| `NOT_PERFORMED` (`BT-UP-05`, `BT-IMG-03` cohesion refactors) | 2 |
| `UNVERIFIED` (`STO-08` browser hypothesis) | 1 |
| `NOT_PERFORMED`(`BT-UP-05`, `BT-IMG-03` 응집도 리팩터링) | 2 |
| `UNVERIFIED`(`STO-08` 브라우저 가설) | 1 |
No finding remains `NOT_STARTED`.
`NOT_STARTED`로 남은 발견은 없다.
### Failures that are NOT claimed as green
### 통과로 주장하지 않는 실패
| Gate | Status | Attribution |
| 게이트 | 상태 | 원인 |
| --- | --- | --- |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 failed | Identical to the baseline capture. Sandbox child-process, cgroup and `/tmp` permission behavior; unrelated to adapters. Count did not change across any task. |
| `corepack pnpm test:browser-capabilities` (webkit) | 6 failed / 24 passed | WebKit cannot launch: missing `libevent-2.1-7t64` and `libavif16`. Chromium passes. **UNVERIFIED**, not PASS. |
| `corepack pnpm test:browser-file-storage-removal` | exit 1 | The reduced-removal-fixture prunes the CI contract to 77/89/102 while `scripts/contracts/ci-gates.ts:481` demands exactly 81/93/105. That file, the CI contract and `scripts/lib/removal-fixture.ts` are **unchanged since the baseline revision** (`git diff --name-only 4dc033c..HEAD` outside `src/`, `tests/` and `docs/` lists only the two Service Worker build scripts), so this is pre-existing, not a regression from this work. |
| `corepack pnpm test:realtime-removal` | exit 1 | Same pre-existing reduced-fixture arithmetic. |
| Server/provider compatibility matrices (presigned V1, Web Push V1/V2, Service Worker V1/V2, OPFS V1/V2) | not run | No provider or multi-release infrastructure in this environment. **UNVERIFIED**. |
| Staging rollback drill | not run | Requires a staging deployment. **UNVERIFIED**. |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19개 실패 | 기준 기록과 같다. sandbox의 자식 프로세스, cgroup, `/tmp` 권한 동작이고 adapter와 관계없다. 어떤 작업에서도 수가 바뀌지 않았다. |
| `corepack pnpm test:browser-capabilities` (webkit) | 6개 실패 / 24개 통과 | WebKit을 실행할 수 없다. `libevent-2.1-7t64`와 `libavif16`이 없다. Chromium은 통과한다. PASS가 아니라 **UNVERIFIED**다. |
| `corepack pnpm test:browser-file-storage-removal` | exit 1 | 축소 제거 fixture(reduced-removal-fixture)는 CI 계약을 77/89/102로 줄이는데, `scripts/contracts/ci-gates.ts:481`은 정확히 81/93/105를 요구한다. 그 파일, CI 계약, `scripts/lib/removal-fixture.ts`는 **기준 리비전 뒤로 바뀌지 않았다**(`src/`, `tests/`, `docs/` 밖에서 `git diff --name-only 4dc033c..HEAD`는 Service Worker 빌드 스크립트 두 개만 보여 준다). 그래서 원래 있던 실패이고, 이 작업이 만든 회귀가 아니다. |
| `corepack pnpm test:realtime-removal` | exit 1 | 같은, 원래 있던 축소 fixture 숫자 문제다. |
| 서버/provider 호환성 매트릭스(presigned V1, Web Push V1/V2, Service Worker V1/V2, OPFS V1/V2) | 돌리지 않음 | 이 환경에는 provider도, 여러 release를 돌릴 인프라도 없다. **UNVERIFIED**. |
| staging rollback drill | 돌리지 않음 | staging 배포가 필요하다. **UNVERIFIED**. |
### Work deliberately not performed
### 일부러 하지 않은 작업
| Plan task | Status | Reason |
| 계획 작업 | 상태 | 이유 |
| --- | --- | --- |
| Task 17 extraction (`BT-UP-05`, `BT-IMG-03`, OPFS/cache/download decomposition) | **NOT PERFORMED** | Pure cohesion refactor with no finding closure. `BT-UP-05` was attempted: the five internal owners extract cleanly, but they need a shared-internals module for ~40 types, constants and helpers to avoid an import cycle, so the attempt was reverted rather than half-landed. `BT-UP-06`, the one item in this group with behavioural content, **was** implemented. |
| `SW-10`, OPFS physical/protocol V2 rollout, presigned and Web Push receipt V2 (`WP-02`, `WP-03`, `WP-04`) | **DEFERRED_TO_MIGRATION** | These are expand → dual-read/emit → old-writer drain → contract deployments requiring server request-shape negotiation and multi-release drain windows. The prerequisite in-repo pieces landed: the shared Service Worker manifest codec and canonical digest (`SW-05`), the OPFS worker protocol version and strict correlation (`STO-07`), and the OPFS physical generation token (`STO-01`). |
| Promotion gaps `GAP-01`, `GAP-02`, `GAP-03`, `R-07`, `BT-UP-07`, `BT-IMG-04` | `PROMOTION_BLOCKED` | Unchanged by design. No availability state was raised and no optional capability was added to the default bootstrap. |
| Task 17 추출(`BT-UP-05`, `BT-IMG-03`, OPFS/캐시/다운로드 분해) | **NOT PERFORMED** | 이것으로 닫히는 발견이 없는 순수 응집도 리팩터링이다. `BT-UP-05`는 시도했다. 내부 owner 다섯 개는 깔끔하게 뽑히지만, import 순환을 피하려면 타입·상수·helper 약 40개를 담은 공유 내부 모듈이 필요하다. 그래서 반만 반영하지 않고 되돌렸다. 이 묶음에서 동작이 바뀌는 유일한 항목인 `BT-UP-06`은 구현**했다**. |
| `SW-10`, OPFS 물리/프로토콜 V2 rollout, presigned와 Web Push receipt V2(`WP-02`, `WP-03`, `WP-04`) | **DEFERRED_TO_MIGRATION** | 이것들은 expand → dual-read/emit → old-writer drain → contract 순서의 배포다. 서버와 요청 모양 협상, 여러 release에 걸친 drain 기간이 필요하다. 저장소 안에서 할 선행 작업은 반영했다. 공유 Service Worker manifest codec과 canonical digest(`SW-05`), OPFS worker 프로토콜 버전과 엄격한 대응(`STO-07`), OPFS 물리 generation token(`STO-01`)이다. |
| Promotion 빈틈 `GAP-01`, `GAP-02`, `GAP-03`, `R-07`, `BT-UP-07`, `BT-IMG-04` | `PROMOTION_BLOCKED` | 설계상 그대로다. availability 상태를 올리지 않았고, 기본 bootstrap에 선택 capability를 더하지 않았다. |
## Re-review remediation (2026-08-14)
## 재검토 후속 수정 (2026-08-14)
Source: [`docs/reviews/adapters/RE-REVIEW-2026-08-14.md`](../reviews/adapters/RE-REVIEW-2026-08-14.md),
38 findings (High 19 / Medium 17 / Low 2) raised against `3b481eb`.
출처: [`docs/reviews/adapters/RE-REVIEW-2026-08-14.md`](../reviews/adapters/RE-REVIEW-2026-08-14.md).
`3b481eb`을 대상으로 낸 발견 38건(High 19 / Medium 17 / Low 2)이다.
**GOV-02.** That re-review found the previous section of this ledger closed a
number of rows as `FIXED_NOT_RELEASED` that were in fact partial. The tables
below are written the other way round: a row is `FIXED` only where a new
adversarial test failed first on the pre-fix source and passes on the landed
one.
**GOV-02.** 그 재검토는 이 원장의 앞 절이 실제로는 부분 수정인 행 여럿을 `FIXED_NOT_RELEASED`로 닫았다는 것을 찾았다. 아래 표는 반대 방향으로 쓴다. 새 적대적(adversarial) 테스트가 수정 전 소스에서 먼저 실패하고 반영된 소스에서 통과할 때만 그 행을 `FIXED`로 적는다.
**All 38 second re-review findings are `FIXED` as scoped below.** The first pass
closed 26; the second closed the remaining twelve, which each needed a lifecycle
or contract change rather than a contained edit. A third re-review then found
that twenty of those closures held only on the paths their tests exercised; that
verdict and its remediation are recorded in the third re-review section further
down, and this section is left as written so the two passes stay comparable.
**두 번째 재검토의 발견 38건은 아래 범위에서 모두 `FIXED`다.** 1차 작업이 26건을 닫았다. 2차 작업이 나머지 12건을 닫았는데, 이들은 국소 수정이 아니라 lifecycle이나 계약 변경이 필요했다. 그 뒤 세 번째 재검토가, 이렇게 닫은 것 가운데 20건이 테스트가 거친 경로에서만 성립한다는 것을 찾았다. 그 판정과 수정은 아래 세 번째 재검토 절에 적었다. 두 작업을 비교할 수 있도록 이 절은 쓴 그대로 둔다.
### Landed
### 반영한 것
| ID | Severity | Disposition | Commit | Red-then-green evidence |
| ID | 심각도 | 처리 | 커밋 | 실패→통과 증거 |
| --- | --- | --- | --- | --- |
| LIVE-01 | High | `FIXED` | `f4bfdf0` | `tests/integration/http-execution-v3-live-authority.test.ts` — UNAVAILABLE, sync throw, async rejection and a malformed outcome each closed as `UNAUTHENTICATED` before the fix; all four now close as `AUTH_INTEGRATION_FAILURE` with zero fetches. |
| LIVE-02 | High | `FIXED` | `f4bfdf0` | `tests/unit/contract-registry-immutability.test.ts` — a borrowed `Map.prototype.clear` emptied the installed profile registry before the fix. |
| LIVE-03 | High | `FIXED` | `f4bfdf0` | Same suite — the composed HTTP registry was clearable and a post-composition mutation of a source policy changed `totalDeadlineMs` from 10000 to 999999. |
| LIVE-04 | Medium | `FIXED` | `f4bfdf0` | Same integration suite — a non-cooperative fetch and reader held the port result open; a body that finished after the deadline was admitted as SUCCESS. |
| LIVE-05 | High | `FIXED` | `f4bfdf0` | Same suite — a DEADLINE timeout emitted no `api.request.failed`. |
| LEG-01 | High | `FIXED` | `ca210d3` | The V2 client's credential authority test (deleted with the V2 client on 2026-11-03) — a recovery that answered after the deadline called `onUnauthenticated` once; it now calls it zero times, and only an adopted no-session result notifies. |
| LEG-02 | High | `FIXED` | `ca210d3` | Same suite — a bearer profile dispatched with no `Authorization` at all. |
| OPT-NET-01 | Medium | `FIXED` | `ca210d3` | `tests/unit/legacy-and-optional-network-remediation.test.ts` — a loader rejection with a live signal became `PAGINATION_ABORTED`. |
| OPT-NET-02 | Low | `FIXED` | `ca210d3` | Same suite — `defineMutationIntent` accepted control characters the executor rejected. |
| STO-RR-01 | High | `FIXED` | `6a8281a` | `tests/unit/opfs-worker-runtime.test.ts` — a strict non-reentrant lease manager made `FINALIZE_PUT` hang forever; `tests/unit/opfs-byte-store.test.ts` pins that a failed finalization is no longer a plain success. |
| STO-RR-02 | Medium | `FIXED` | `6a8281a` | Same suite — every failure answered with kind `CAPABILITIES`. |
| STO-RR-03 | Medium | `FIXED` | `6a8281a` | Same suite — `{code:"EVIL"}` reached the caller; a non-boolean `retryable` and a throwing getter left the RPC to time out. |
| STO-RR-04 | Medium | `FIXED` | `6a8281a` | `tests/unit/public-response-cache.test.ts` — a transient marker read failure deleted the active candidate. |
| STO-RR-05 | Medium | `FIXED` | `6a8281a` | Same suite — one failed repair fetch destroyed every healthy asset in the release. |
| RPC-RR-02 | Medium | `FIXED` | `bd90e0c` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — a throwing fence and a throwing `clock.sleep` escaped the Result contract. |
| RPC-RR-03 | High | `FIXED` | `bd90e0c` | Same suite — a transport accessor ran during validation, and the installed binding registries exposed `set`/`delete`/`clear`. |
| RPC-RR-04 | Medium | `FIXED` | `bd90e0c` | Same suite — extra, inherited, symbol-keyed and throwing-getter transport values passed. |
| SW-RR-01 | High | `FIXED` | `efc577d` | Bounded marker reader with a read deadline, reader cancel and fatal UTF-8 decode replaces `response.text()`. |
| SW-RR-02 | Medium | `FIXED` | `efc577d` | A `null` `event.source` no longer satisfies activation or reset completion. |
| SW-RR-03 | Medium | `FIXED` | `efc577d` | `tests/unit/service-worker-web-push-remediation.test.ts` plus the `check:adapter-inventory` gate — generator and decoder now share one exported table. |
| SW-RR-04 | Medium | `FIXED` | `efc577d` | `cache.match` rejection is closed as a miss so `respondWith` reaches its network fallback. |
| WP-RR-01 | Medium | `FIXED` | `efc577d` | `focus`/`openWindow` carry NOT_APPLIED → MAYBE_APPLIED → CONFIRMED and a late effect is observed exactly once. |
| TR-RR-08 | Medium | `FIXED` | `69cb7e3` | `tests/unit/resumable-upload-http-control-plane.test.ts` — a throwing getter escaped as `TypeError` out of `createSession`; symbol and non-enumerable extras passed the key check. |
| TR-RR-09 | Medium | `FIXED` | `fb5b449` | `tests/unit/image-cdn-runtime.test.ts` — the suite pinned the contradictory `private, no-store` as success; the recorded fail-closed matrix now applies. |
| GOV-01 | Low | `FIXED` | this commit | `scripts/check-adapter-inventory.ts` diffs `docs/reviews/adapters/INVENTORY.md` against `git ls-files src/adapters`. The missing `src/adapters/platform/abortable-operation.ts` row is restored and the total is 119/119. |
| GOV-02 | Medium | `FIXED` | this commit | This section replaces the over-closed rows with evidence-linked dispositions and an explicit not-done list. |
| LIVE-01 | High | `FIXED` | `f4bfdf0` | `tests/integration/http-execution-v3-live-authority.test.ts` — 수정 전에는 UNAVAILABLE, 동기 throw, 비동기 rejection, 잘못된 모양의 결과가 각각 `UNAUTHENTICATED`로 닫혔다. 이제 넷 다 fetch 0회로 `AUTH_INTEGRATION_FAILURE`로 닫힌다. |
| LIVE-02 | High | `FIXED` | `f4bfdf0` | `tests/unit/contract-registry-immutability.test.ts` — 수정 전에는 빌려 온 `Map.prototype.clear`가 설치된 profile registry를 비웠다. |
| LIVE-03 | High | `FIXED` | `f4bfdf0` | 같은 테스트 파일 — 조립된 HTTP registry를 비울 수 있었고, 조립 뒤 원본 정책을 바꾸면 `totalDeadlineMs`가 10000에서 999999로 바뀌었다. |
| LIVE-04 | Medium | `FIXED` | `f4bfdf0` | 같은 integration 테스트 파일 — 협조하지 않는 fetch와 reader가 port 결과를 열린 채로 붙잡았다. deadline 뒤에 끝난 body를 SUCCESS로 받아들였다. |
| LIVE-05 | High | `FIXED` | `f4bfdf0` | 같은 테스트 파일 — DEADLINE timeout이 `api.request.failed`를 내보내지 않았다. |
| LEG-01 | High | `FIXED` | `ca210d3` | V2 client의 credential authority 테스트(2026-11-03에 V2 client와 함께 지웠다) — deadline 뒤에 답한 recovery가 `onUnauthenticated`를 한 번 불렀다. 이제는 0번 부르고, 채택된 no-session 결과만 알린다. |
| LEG-02 | High | `FIXED` | `ca210d3` | 같은 테스트 파일 — bearer profile이 `Authorization` 없이 요청을 보냈다. |
| OPT-NET-01 | Medium | `FIXED` | `ca210d3` | `tests/unit/legacy-and-optional-network-remediation.test.ts` — signal이 살아 있는데 loader rejection이 `PAGINATION_ABORTED`가 됐다. |
| OPT-NET-02 | Low | `FIXED` | `ca210d3` | 같은 테스트 파일 — `defineMutationIntent`가 executor는 거부하는 제어 문자를 받아들였다. |
| STO-RR-01 | High | `FIXED` | `6a8281a` | `tests/unit/opfs-worker-runtime.test.ts` — 엄격한 비재진입 lease manager 때문에 `FINALIZE_PUT`이 영원히 멈췄다. `tests/unit/opfs-byte-store.test.ts`는 실패한 finalization이 더는 단순 성공이 아님을 고정한다. |
| STO-RR-02 | Medium | `FIXED` | `6a8281a` | 같은 테스트 파일 — 모든 실패가 kind `CAPABILITIES`로 답했다. |
| STO-RR-03 | Medium | `FIXED` | `6a8281a` | 같은 테스트 파일 — `{code:"EVIL"}`이 호출자에게 닿았다. boolean이 아닌 `retryable`과 예외를 던지는 getter 때문에 RPC가 timeout까지 갔다. |
| STO-RR-04 | Medium | `FIXED` | `6a8281a` | `tests/unit/public-response-cache.test.ts` — 일시적인 marker 읽기 실패가 활성 후보를 지웠다. |
| STO-RR-05 | Medium | `FIXED` | `6a8281a` | 같은 테스트 파일 — repair fetch 하나가 실패하자 그 release의 정상 asset이 다 지워졌다. |
| RPC-RR-02 | Medium | `FIXED` | `bd90e0c` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — 예외를 던지는 fence와 예외를 던지는 `clock.sleep`이 Result 계약을 빠져나갔다. |
| RPC-RR-03 | High | `FIXED` | `bd90e0c` | 같은 테스트 파일 — 검증 중에 transport accessor가 실행됐고, 설치된 binding registry가 `set`/`delete`/`clear`를 드러냈다. |
| RPC-RR-04 | Medium | `FIXED` | `bd90e0c` | 같은 테스트 파일 — 남는 필드, 상속된 필드, symbol 키, 예외를 던지는 getter가 있는 transport 값이 통과했다. |
| SW-RR-01 | High | `FIXED` | `efc577d` | 읽기 deadline, reader 취소, fatal UTF-8 디코딩을 갖춘 크기 제한 marker reader가 `response.text()`를 대신한다. |
| SW-RR-02 | Medium | `FIXED` | `efc577d` | `null`인 `event.source`는 더는 activation이나 reset 완료 조건을 채우지 않는다. |
| SW-RR-03 | Medium | `FIXED` | `efc577d` | `tests/unit/service-worker-web-push-remediation.test.ts`와 `check:adapter-inventory` 게이트 — 이제 generator와 decoder가 export된 표 하나를 같이 쓴다. |
| SW-RR-04 | Medium | `FIXED` | `efc577d` | `cache.match` rejection을 miss로 닫아서 `respondWith`가 네트워크 fallback까지 간다. |
| WP-RR-01 | Medium | `FIXED` | `efc577d` | `focus`/`openWindow`가 NOT_APPLIED → MAYBE_APPLIED → CONFIRMED를 따르고, 늦은 effect는 정확히 한 번 관찰한다. |
| TR-RR-08 | Medium | `FIXED` | `69cb7e3` | `tests/unit/resumable-upload-http-control-plane.test.ts` — 예외를 던지는 getter가 `TypeError`로 `createSession` 밖으로 새어 나갔다. symbol 키와 열거되지 않는 남는 필드가 키 검사를 통과했다. |
| TR-RR-09 | Medium | `FIXED` | `fb5b449` | `tests/unit/image-cdn-runtime.test.ts` — 테스트가 서로 모순인 `private, no-store`를 성공으로 고정했었다. 이제 기록된 fail-closed 매트릭스를 적용한다. |
| GOV-01 | Low | `FIXED` | 이 커밋 | `scripts/check-adapter-inventory.ts`가 `docs/reviews/adapters/INVENTORY.md`를 `git ls-files src/adapters`와 비교한다. 빠졌던 `src/adapters/platform/abortable-operation.ts` 행을 되살렸고, 합계는 119/119다. |
| GOV-02 | Medium | `FIXED` | 이 커밋 | 이 절은 너무 일찍 닫은 행을, 증거가 연결된 처리 결과와 하지 않은 일을 명시한 목록으로 바꾼다. |
### Landed in the second pass
### 2차 작업에서 반영한 것
The twelve findings the first pass did not reach are now closed on the same
terms: a named adversarial test failed on the pre-fix source and passes on the
landed one.
1차 작업이 닿지 못한 발견 12건도 이제 같은 조건으로 닫았다. 이름을 밝힌 적대적 테스트가 수정 전 소스에서 실패하고, 반영된 소스에서 통과한다.
| ID | Severity | Commit | Red-then-green evidence |
| ID | 심각도 | 커밋 | 실패→통과 증거 |
| --- | --- | --- | --- |
| RPC-RR-01 | High | `a7390e3` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — `openServerStream` returns a lease (`streamId`, `frames`, `cancel`, `waitClosed`) decoded from own data descriptors. A timed-out stream is cancelled exactly once, a second stream for the same operation is refused as `CONFLICT` / `RPC_STREAM_DRAINING` without reaching the transport, and admission resumes only after `waitClosed()` settles. |
| RT-RR-01 | High | `c0f53d1` | `tests/unit/realtime/stream-coordinator.test.ts` — a `close()` during a running apply reported success before the fix; tasks are now registered at invocation, so it reports `IDLE_TIMEOUT` and `DRAINING`. |
| RT-RR-02 | High | `c0f53d1` | Same suite — a queued event started running inside DRAINING, and a timed-out effect left its resume token in place. The queued event is now dropped as `CLOSED` at execution time and the token is discarded with `freshness: UNKNOWN`. |
| RT-RR-03 | Medium | `c0f53d1` | `tests/unit/realtime/live-poll-handoff-coordinator.test.ts` — a second `close()` replayed the cached timeout forever; only an in-flight close is shared now, fenced writers are retained until their tails settle, and a later close converges to success. |
| RT-RR-04 | High | `c0f53d1` | Same suite — `close()` reported quiescence while a checkpoint was still running; checkpoint work now joins the physical-task registry. |
| TR-RR-05 | High | `46e067e` | `tests/unit/abortable-operation.test.ts` — a rejection was reported as `TERMINAL/CLOSED` while `terminal()` said no owner, and a throwing scheduler released the caller listener leaving no owner at all, so later aborts were invisible. The primitive now distinguishes `REJECTED`, agrees with `terminal()`, snapshots the scheduler, closes atomically on install failure and compensates a late value exactly once. Both presigned subsystems migrated onto it, replacing two hand-written copies. |
| TR-RR-01 | High | `46e067e` | `tests/unit/presigned-transfer.test.ts` — `close()` released bookkeeping without aborting, and the consumer signal joined only after the fetch began. Both are fixed; the scheduler-failure test now pins fail-closed. |
| TR-RR-02 | High | `46e067e` | The upload scope is created before the digest and the digest races the caller and deadline; the vault claim and network call follow an owner re-check. |
| TR-RR-03 | High | `46e067e` | Same suite — the registration is a versioned exact union: unknown/missing protocol version, plaintext target, ambient credential and cookie headers, a non-2xx expected status and any extra own field are each refused at the issuer seam. |
| TR-RR-04 | Medium | `5a76f95` | Same suite — the presigned source was never closed on success, writer failure or abort; a holder now closes it exactly once at the outermost boundary on all three. |
| TR-RR-06 | High | `5a76f95` | `tests/unit/resumable-upload-runtime.test.ts` — a never-granting mutation lock made `dispose()` unbounded; it is now bounded by `cleanupDeadlineMs`, returns the drain result, and leaves the runtime `CLOSING` with the checkpoint store open when the drain is unproved. |
| TR-RR-07 | High | `5a76f95` | `tests/unit/image-cdn-runtime.test.ts` — after an abort a new verification was admitted while the abandoned verifier still ran; the slot is now held until the raw verifier settles. |
| RPC-RR-01 | High | `a7390e3` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — `openServerStream`이 자기 data descriptor에서 디코딩한 lease(`streamId`, `frames`, `cancel`, `waitClosed`)를 돌려준다. 시간이 다 된 stream은 정확히 한 번 취소한다. 같은 작업의 두 번째 stream은 transport에 닿기 전에 `CONFLICT` / `RPC_STREAM_DRAINING`으로 거부한다. 새 stream 받기는 `waitClosed()`가 끝난 뒤에만 다시 연다. |
| RT-RR-01 | High | `c0f53d1` | `tests/unit/realtime/stream-coordinator.test.ts` — 수정 전에는 apply가 도는 중에 부른 `close()`가 성공을 보고했다. 이제 작업을 호출 시점에 등록하므로 `IDLE_TIMEOUT`과 `DRAINING`을 보고한다. |
| RT-RR-02 | High | `c0f53d1` | 같은 테스트 파일 — 대기열의 event가 DRAINING 안에서 실행을 시작했고, 시간이 다 된 effect가 resume token을 그대로 남겼다. 이제 대기열의 event는 실행 시점에 `CLOSED`로 버리고, token은 `freshness: UNKNOWN`과 함께 폐기한다. |
| RT-RR-03 | Medium | `c0f53d1` | `tests/unit/realtime/live-poll-handoff-coordinator.test.ts` — 두 번째 `close()`가 캐시된 timeout을 끝없이 되풀이했다. 이제 진행 중인 close만 공유한다. fence된 writer는 남은 작업이 끝날 때까지 붙잡아 두고, 나중의 close는 결국 성공으로 수렴한다. |
| RT-RR-04 | High | `c0f53d1` | 같은 테스트 파일 — checkpoint가 아직 도는데 `close()`가 작업이 멈췄다(quiescence)고 보고했다. 이제 checkpoint 작업도 physical-task registry에 들어간다. |
| TR-RR-05 | High | `46e067e` | `tests/unit/abortable-operation.test.ts` — `terminal()`은 owner가 없다고 하는데 rejection을 `TERMINAL/CLOSED`로 보고했다. 예외를 던지는 scheduler가 호출자 listener를 풀어 owner가 아예 없어졌고, 그래서 뒤이은 abort가 보이지 않았다. 이제 이 primitive는 `REJECTED`를 구분하고, `terminal()`과 일치하며, scheduler를 snapshot하고, 설치에 실패하면 원자적으로 닫고, 늦은 값을 정확히 한 번 보상한다. presigned 하위 시스템 둘이 다 이 primitive로 옮겨, 손으로 쓴 사본 두 개를 대신했다. |
| TR-RR-01 | High | `46e067e` | `tests/unit/presigned-transfer.test.ts` — `close()`가 abort 없이 내부 기록만 풀었고, consumer signal은 fetch가 시작된 뒤에야 합류했다. 둘 다 고쳤다. scheduler 실패 테스트는 이제 fail-closed를 고정한다. |
| TR-RR-02 | High | `46e067e` | upload scope를 digest 전에 만들고, digest는 호출자·deadline과 경주한다. vault claim과 네트워크 호출은 owner를 다시 확인한 뒤에 한다. |
| TR-RR-03 | High | `46e067e` | 같은 테스트 파일 — 등록 값은 버전이 붙은 exact union이다. 모르는/없는 protocol 버전, 평문 target, ambient credential과 cookie 헤더, 2xx가 아닌 기대 status, 남는 own 필드는 각각 issuer 경계에서 거부한다. |
| TR-RR-04 | Medium | `5a76f95` | 같은 테스트 파일 — presigned source를 성공, writer 실패, abort 어느 때도 닫지 않았다. 이제 holder가 세 경우 각각 가장 바깥 경계에서 정확히 한 번 닫는다. |
| TR-RR-06 | High | `5a76f95` | `tests/unit/resumable-upload-runtime.test.ts` — 끝내 lock을 주지 않는 mutation lock 때문에 `dispose()`에 끝이 없었다. 이제 `cleanupDeadlineMs`로 제한하고, drain 결과를 돌려주며, drain이 증명되지 않으면 checkpoint store를 연 채로 runtime을 `CLOSING`에 둔다. |
| TR-RR-07 | High | `5a76f95` | `tests/unit/image-cdn-runtime.test.ts` — abort 뒤에, 버린 verifier가 아직 도는데 새 검증을 받아들였다. 이제 원래 verifier가 끝날 때까지 자리를 붙잡아 둔다. |
**No second re-review row remains `NOT_STARTED`**, and the
structural gate for the shared `abortable-operation` primitive is now active —
it was withheld until the primitive actually had production importers, because a
gate that fails CI for a documented but unfixed defect reports the wrong thing.
**두 번째 재검토의 행 가운데 `NOT_STARTED`로 남은 것은 없다.** 공유 `abortable-operation` primitive의 구조 게이트도 이제 켜져 있다. primitive를 실제로 import하는 production 코드가 생길 때까지 이 게이트를 미뤘다. 문서에 적혔지만 아직 고치지 않은 결함으로 CI를 실패시키는 게이트는 잘못된 것을 보고하기 때문이다.
Contracts that changed shape, and are therefore breaking for an external
implementor:
모양이 바뀌어서 외부 구현자에게는 호환이 깨지는 계약:
| Contract | Change | Reason |
| 계약 | 변경 | 이유 |
| --- | --- | --- |
| `BrowserRpcTransport.openServerStream` | returns `BrowserRpcServerStreamLease` instead of `AsyncIterable` | RPC-RR-01 needs cancellation and closure evidence |
| `AuthSessionPort.recover` | accepts an optional `CredentialOperationContext` | LEG-01; optional for one release |
| `PresignedCapabilityRegistration` | gains `protocol` | TR-RR-03 versioned exact union |
| `ResumableUploadRuntime.dispose` | returns `BrowserDataResult<void>` | TR-RR-06 bounded drain result |
| `ResumableUploadRuntimePolicy` | gains `cleanupDeadlineMs` | TR-RR-06 teardown bound |
| `ImageCdnPresentationPort.resolve` | `signal` required | BT-IMG-01, landed earlier |
| `BrowserRpcTransport.openServerStream` | `AsyncIterable` 대신 `BrowserRpcServerStreamLease`를 돌려준다 | RPC-RR-01에 취소와 닫힘 증거가 필요하다 |
| `AuthSessionPort.recover` | 선택 인자 `CredentialOperationContext`를 받는다 | LEG-01. 한 release 동안은 선택이다 |
| `PresignedCapabilityRegistration` | `protocol`이 생긴다 | TR-RR-03 버전 붙은 exact union |
| `ResumableUploadRuntime.dispose` | `BrowserDataResult<void>`를 돌려준다 | TR-RR-06 제한된 drain 결과 |
| `ResumableUploadRuntimePolicy` | `cleanupDeadlineMs`가 생긴다 | TR-RR-06 teardown 한도 |
| `ImageCdnPresentationPort.resolve` | `signal` 필수 | BT-IMG-01, 먼저 반영 |
### Gates after this pass
### 이 작업 뒤 게이트
Run on the landed tree. Only what actually passed is claimed as passing.
반영된 트리에서 돌렸다. 실제로 통과한 것만 통과로 적는다.
| Command | Exit | Result |
| 명령 | 종료 | 결과 |
| --- | ---: | --- |
| `corepack pnpm check:types` | 0 | all six projects |
| `corepack pnpm lint` | 0 | `--max-warnings=0` clean |
| `corepack pnpm check:architecture` | 0 | 289 modules, 868 dependencies; 12 fixtures PASS |
| `corepack pnpm check:adapter-inventory` | 0 | 119 files, 7 shared asset extensions, fixture linking, primitive importers |
| `corepack pnpm check:registries` | 0 | 11 registries PASS |
| `corepack pnpm check:diagnostics` | 0 | 8 diagnostics / 5 telemetry producers |
| `corepack pnpm check:browser-file-storage-boundaries` | 0 | PASS, 34 rejections |
| `corepack pnpm check:types` | 0 | 여섯 프로젝트 모두 |
| `corepack pnpm lint` | 0 | `--max-warnings=0`로 경고 없음 |
| `corepack pnpm check:architecture` | 0 | 모듈 289개, 의존 868개. fixture 12개 PASS |
| `corepack pnpm check:adapter-inventory` | 0 | 파일 119개, 공유 asset 확장자 7개, fixture 연결, primitive importer |
| `corepack pnpm check:registries` | 0 | registry 11개 PASS |
| `corepack pnpm check:diagnostics` | 0 | diagnostic 8개 / telemetry producer 5개 |
| `corepack pnpm check:browser-file-storage-boundaries` | 0 | PASS, 거부 34건 |
| `corepack pnpm check:realtime-boundaries` | 0 | PASS |
| `corepack pnpm verify:documentation` | 0 | PASS_SCOPED |
| `git diff --check` | 0 | clean |
| `tests/unit` + `tests/integration`, no exclusions | — | 1643 passed / 1747; the 104 failures are the four environmental files below |
| `corepack pnpm test:component` | 0 | 126 passed |
| `corepack pnpm test:recipes` | 0 | 17 passed |
| 참조 샘플 기능 시험(그 script는 2026-11-07 샘플과 함께 지웠다) | 0 | 26 passed |
| `git diff --check` | 0 | 문제 없음 |
| `tests/unit` + `tests/integration`, 제외 없음 | — | 1643개 통과 / 1747개. 실패 104개는 아래 환경 탓 파일 네 개에서 나온다 |
| `corepack pnpm test:component` | 0 | 126개 통과 |
| `corepack pnpm test:recipes` | 0 | 17개 통과 |
| 참조 샘플 기능 시험(그 script는 2026-11-07 샘플과 함께 지웠다) | 0 | 26개 통과 |
### Environmental failures, not claimed as green
### 통과로 주장하지 않는 환경 실패
| Gate | Status | Attribution |
| 게이트 | 상태 | 원인 |
| --- | --- | --- |
| tests/unit/ci-workflow-generation.test.ts | 82 failed / 325 passed | Identical on the pre-change baseline (`git stash` comparison). The subprocess gates it spawns cannot run in this sandbox. |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | fails | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
| `tests/unit/security-followup.test.ts`, `tests/integration/provider-guardian-transaction.test.ts`, `tests/unit/risk-coverage.test.ts` | flaky under full-suite load | Historical baseline result. All three passed in a fresh process (78 passed together). |
| tests/unit/ci-workflow-generation.test.ts | 82개 실패 / 325개 통과 | 변경 전 기준에서도 같다(`git stash` 비교). 이 파일이 띄우는 하위 프로세스 게이트는 이 sandbox에서 돌 수 없다. |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 실패 | 원래 있던 그대로의 sandbox, cgroup, `/tmp` 권한 동작이다. |
| `tests/unit/security-followup.test.ts`, `tests/integration/provider-guardian-transaction.test.ts`, `tests/unit/risk-coverage.test.ts` | 전체 실행 부하에서 불안정(flaky) | 과거 기준 결과다. 셋 다 새 프로세스에서 통과했다(함께 돌려 78개 통과). |
> Current classification update (2026-09-18): the provider guardian transaction
> suite moved to `tests/integration/provider-guardian-transaction.test.ts`.
> It spawns child processes and exercises filesystem/IPC/process lifecycle, so it
> is not part of the pure unit pool. Its READY/PUBLISHED wait uses a dedicated
> test watchdog rather than treating a 1-second scheduler delay as a production
> protocol deadline.
> 현재 분류 갱신(2026-09-18): provider guardian transaction 테스트 파일은 `tests/integration/provider-guardian-transaction.test.ts`로 옮겼다.
> 이 파일은 자식 프로세스를 띄우고 파일 시스템/IPC/프로세스 lifecycle을 다룬다. 그래서 순수 unit 묶음에 넣지 않는다.
> READY/PUBLISHED 대기에는 전용 테스트 watchdog을 쓴다. 1초 scheduler 지연을 production 프로토콜 deadline으로 보지 않는다.
### Destructive fixture hazard — fixed
### 파괴적인 fixture 위험 — 고침
Outside the 38 findings, and found while running the suites for them.
발견 38건 밖의 일이고, 그 발견을 위한 테스트를 돌리다가 찾았다.
Four sites linked the repository's installed dependencies into a throwaway
fixture with a single directory symlink at `<fixture>/node_modules`:
네 곳이 저장소에 설치된 의존성을 쓰고 버릴 fixture에 연결할 때, `<fixture>/node_modules`에 디렉터리 symlink 하나를 썼다:
- `scripts/lib/removal-fixture.ts`
- `scripts/check-supply-chain-provider-fixtures.ts`
- `tests/integration/security-followup-archive.test.ts`
- `tests/system/ci-runner/ci-artifact-contract.test.ts`
Each fixture then runs `pnpm` inside itself. pnpm does not recognise the modules
directory it finds there and purges it; with `CI=true` it does so without a
prompt. The purge followed the symlink and deleted the **repository's own**
`node_modules` mid-run — a test suite uninstalling the workspace it was running
in. That is what produced the cascading, file-unrelated failures a full
`test:unit` run reported, and it happened twice during this work.
그다음 각 fixture는 자기 안에서 `pnpm`을 돌린다. pnpm은 거기서 찾은 modules 디렉터리를 알아보지 못하고 지운다. `CI=true`이면 묻지도 않고 지운다. 이 삭제가 symlink를 따라가 실행 도중 **저장소 자신의** `node_modules`를 지웠다. 테스트가 자기가 돌고 있는 workspace를 언인스톨한 셈이다. 전체 `test:unit` 실행이 보고한, 파일과 관계없이 줄줄이 이어진 실패가 여기서 나왔다. 이 작업 중에 두 번 일어났다.
`scripts/lib/fixture-node-modules.ts` replaces all four: `node_modules` is a
real directory whose entries are individual symlinks, so a recursive delete
unlinks the fixture's own links instead of walking through one link into the
shared tree. `tests/unit/fixture-node-modules.test.ts` performs the exact
recursive delete pnpm performs and asserts the source tree survives, and
`corepack pnpm check:adapter-inventory` fails on any reintroduction of the
directory-symlink form.
`scripts/lib/fixture-node-modules.ts`가 네 곳을 다 대신한다. `node_modules`는 진짜 디렉터리이고, 그 안의 항목이 각각 symlink다. 그래서 재귀 삭제는 링크 하나를 타고 공유 트리로 들어가지 않고, fixture 자신의 링크만 끊는다. `tests/unit/fixture-node-modules.test.ts`는 pnpm이 하는 재귀 삭제를 그대로 해 보고 원본 트리가 살아남는지 확인한다. `corepack pnpm check:adapter-inventory`는 디렉터리 symlink 방식이 다시 들어오면 실패한다.
After the fix a full `tests/unit` + `tests/integration` run leaves the
dependencies intact and its failures are confined to the two environmental
files above plus the two flaky-under-load ones:
고친 뒤에는 전체 `tests/unit` + `tests/integration` 실행이 의존성을 그대로 둔다. 실패는 위의 환경 탓 파일 두 개와, 부하에서 불안정한 파일 두 개로 좁혀진다:
| File | Failed | Attribution |
| 파일 | 실패 | 원인 |
| --- | ---: | --- |
| tests/unit/ci-workflow-generation.test.ts | 82 | Identical on the pre-change baseline (`git stash` comparison). Its subprocess gates cannot run in this sandbox. |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
| `tests/unit/security-followup.test.ts` | 2 | Passes in isolation. |
| `tests/integration/provider-guardian-transaction.test.ts` | 1 | Historical baseline: passed in isolation; current suite is classified as process integration. |
| tests/unit/ci-workflow-generation.test.ts | 82 | 변경 전 기준에서도 같다(`git stash` 비교). 이 파일의 하위 프로세스 게이트는 이 sandbox에서 돌 수 없다. |
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 | 원래 있던 그대로의 sandbox, cgroup, `/tmp` 권한 동작이다. |
| `tests/unit/security-followup.test.ts` | 2 | 따로 돌리면 통과한다. |
| `tests/integration/provider-guardian-transaction.test.ts` | 1 | 과거 기준: 따로 돌리면 통과했다. 지금은 프로세스 integration 테스트로 분류한다. |
1619 passed / 1723 total, and tests/unit/removal-fixture.test.ts,
`tests/unit/supply-chain.test.ts` and
`tests/integration/security-followup-archive.test.ts` — the three that had to be
excluded before — now pass in the full run.
전체 1723개 중 1619개 통과다. 전에는 빼야 했던 세 파일 tests/unit/removal-fixture.test.ts,
`tests/unit/supply-chain.test.ts`,
`tests/integration/security-followup-archive.test.ts`도 이제 전체 실행에서 통과한다.
## Third re-review (2026-08-14)
## 세 번째 재검토 (2026-08-14)
A third read-only re-review re-tested all 38 rows above against hostile,
non-cooperative, late-completing and mutable inputs. It confirmed 18 as fixed
and found 20 that held only on the paths their tests exercised, plus three new
findings and three governance defects. The common shape was the same in almost
every case: a value was **checked and then read again**, or a wrapper settled
and was mistaken for the physical work it was bounding.
읽기만 하는 세 번째 재검토가 위의 38행 전체를 적대적이고, 협조하지 않고, 늦게 끝나고, 값이 바뀌는 입력으로 다시 시험했다. 18건은 고쳐졌다고 확인했다. 20건은 테스트가 거친 경로에서만 성립했다. 새 발견 3건과 거버넌스(governance) 결함 3건도 찾았다. 거의 모든 경우에 모양이 같았다. 값을 **확인한 뒤 다시 읽었거나**, wrapper가 끝난 것을 그 wrapper가 제한하던 실제 작업이 끝난 것으로 착각했다.
`docs/operations/adapter-remediation-dispositions.json` is the machine-readable
record; `corepack pnpm check:remediation-ledger` joins it against this document,
verifies every named evidence path exists, and refuses a blanket closure
sentence while any row is still open. **GOV-03.** The previous section claimed
"All 38 are now FIXED" while six rows were reproducibly partial — a sentence is
cheap and a reviewer reads it as evidence, so the claim is now derived rather
than authored.
`docs/operations/adapter-remediation-dispositions.json`이 기계가 읽는 기록이다. `corepack pnpm check:remediation-ledger`는 그 파일을 이 문서와 맞대어 보고, 적힌 증거 경로가 다 있는지 확인한다. 아직 열린 행이 하나라도 있으면 일괄 종료를 선언하는 문장을 거부한다. **GOV-03.** 앞 절은 여섯 행이 재현 가능하게 부분 수정이었는데도 "All 38 are now FIXED"라고 적었다. 문장은 쓰기 쉽고, 리뷰어는 그 문장을 증거로 읽는다. 그래서 이제 그 주장을 사람이 쓰지 않고 기록에서 끌어낸다.
### Landed
### 반영한 것
| ID | Prior verdict | Disposition | Red-then-green evidence |
| ID | 이전 판정 | 처리 | 실패→통과 증거 |
| --- | --- | --- | --- |
| NS-01 | `PARTIAL` | `FIXED` | `tests/integration/http-execution-v3-live-authority.test.ts` — a throwing `kind` getter escaped the auth boundary and an auth outage was reported as `NETWORK_FAILURE`; nine hostile credential shapes now close as `AUTH_INTEGRATION_FAILURE` with zero fetches, and each field is read exactly once. |
| NS-02 | `PARTIAL` | `FIXED` | `tests/unit/contract-registry-immutability.test.ts` — a policy that answered `10_000` to validation and `999_999` to the copy installed the second value; composition now snapshots first, so the out-of-ceiling value is refused. |
| NS-03 | `PARTIAL` | `FIXED` | `tests/integration/http-execution-v3-live-authority.test.ts` — a `NONE` probe left `body.locked === true` after a deadline; the reader is now cancelled once and its lock released. |
| NS-04 | `PARTIAL` | `FIXED` | `tests/unit/opfs-byte-store.test.ts` — a failed `journal.complete` still returned plain success with `SUCCEEDED` telemetry; it now returns a `RECONCILE` failure and leaves the row `COMMITTED`, and an unfinished delete is observed `DEGRADED`. |
| NS-05 | `PARTIAL` | `FIXED` | `tests/unit/opfs-worker-runtime.test.ts` — a bootstrap failure answered every request with kind `CAPABILITIES`, so the gateway replaced `BLOCKED` with `UNSUPPORTED`; all twelve kinds now round-trip their own correlation. |
| NS-06 | `PARTIAL` | `FIXED` | Same suite — a throwing `requestId` getter produced an RPC timeout and a stateful trap left the public promise pending forever; replies are decoded before the pending row is released and an uncorrelatable reply fails the channel closed. |
| NS-07 | `NEW` | `FIXED` | `tests/unit/cursor-pagination-runtime.test.ts` — raising `maxPages` after construction widened a validated cap from one page to three; caps and collaborators are captured once. |
| NS-08 | `NEW` | `FIXED` | `tests/unit/public-response-cache.test.ts` — a non-cooperative fetch held the mutation lock forever, and a digest finishing after the abort still wrote the asset and the activation marker; one terminal owner now covers the whole staging body. |
| RPC-01 | `PARTIAL` | `FIXED` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — a rejecting, throwing or non-promise `waitClosed()` was absorbed into success and a second physical stream opened; only a fulfilled contract-shaped receipt prunes the registration. |
| RPC-02 | `PARTIAL` | `FIXED` | Same suite — a throwing iterator `return` accessor replaced the selected timeout with a native `TypeError`, and the exported lease decoder threw on a hostile `Symbol.asyncIterator`. |
| RPC-03 | `PARTIAL` | `FIXED` | Same suite — a registry accessor ran twice during validation and rows hiding fields behind a prototype or a non-enumerable key installed; every registry is snapshotted before validation. |
| RPC-04 | `PARTIAL` | `FIXED` | Same suite — own `{ok,message,encodedBytes}` plus a prototype `injected` was a success, and a missing `message` reached a permissive schema as `undefined`. |
| RT-01 | `PARTIAL` | `FIXED` | `tests/unit/realtime/stream-coordinator.test.ts` — an authority that re-entered `close()` from inside its own invocation got `{ok:true}` while its effect was pending; the task is registered before the collaborator is called. |
| RT-02 | `NEW` | `FIXED` | Same suite — a throwing `scheduleTimeout` started a recovery that overlapped the running apply and made `close()` reject with a native `TypeError`; an uninstallable deadline now fails closed inside the result contract. |
| TR-01 | `PARTIAL` | `FIXED` | `tests/unit/presigned-transfer.test.ts` — a stateful issuer could show an allowed header set to the forbidden-header check and store `Authorization`; the registration and everything nested in it is snapshotted before validation. |
| TR-02 | `PARTIAL` | `FIXED` | `tests/unit/presigned-transfer-delivery.test.ts` — a source lease that resolved after an abort was never closed; a compensator sharing the holder's close-once latch closes it exactly once. |
| TR-03 | `PARTIAL` | `FIXED` | `tests/unit/abortable-operation.test.ts`, `tests/unit/image-cdn-browser-probe.test.ts`, `tests/unit/resumable-upload-fetch-transport.test.ts` — the outcome depended on a hard-coded four-microtask drain, and a throwing scheduler rejected `probe()`/`execute()` natively while leaking a caller listener. The primitive now settles once by observation order, and all four consumers use it with construction-time bound timer snapshots. |
| TR-04 | `PARTIAL` | `FIXED` | `tests/unit/resumable-upload-runtime-teardown.test.ts` — a provider outliving its attempt deadline let `dispose()` report a drained runtime and close the checkpoint store; raw provider work is now its own registry and both must be quiescent. |
| TR-05 | `PARTIAL` | `FIXED` | `tests/unit/resumable-upload-http-control-plane.test.ts` — a stateful `sessionId` passed the regex and returned `../../unsafe`; the decoder validates an owned snapshot read exactly once. |
| SW-01 | `PARTIAL` | `FIXED` | `tests/unit/service-worker-runtime.test.ts` — a single 1 MiB chunk was retained before the 257-byte ceiling was compared, a declared oversize left the body open and the reader lock was never released. |
| SW-02 | `PARTIAL` | `FIXED` | `tests/unit/service-worker-web-push-remediation.test.ts` — the generator emitted `/assets/bad@name-abcdefgh.js` and the decoder then refused the manifest it had just produced; both share one canonical path predicate and the generator self-validates its output. |
| WP-01 | `PARTIAL` | `FIXED` | `tests/unit/web-push-worker-runtime.test.ts` — an ordinary click was counted twice, a late rejection downgraded `MAYBE_APPLIED` to `NOT_APPLIED`, and the late observation ran outside `waitUntil`. |
| GOV-03 | `OPEN` | `FIXED` | `scripts/check-remediation-ledger.ts` — dispositions and evidence paths are machine-readable and a blanket closure sentence is blocked while any row is open. |
| GOV-04 | `OPEN` | `FIXED` | `scripts/check-adapter-inventory.ts` — the gate passed on any single importer; it now requires the four named consumers to resolve their import to the shared primitive and prints the exact set. |
| GOV-05 | `OPEN` | `FIXED` | `config/recipes/frontend-capability-recipes.json` — see the budget note below. |
| NS-01 | `PARTIAL` | `FIXED` | `tests/integration/http-execution-v3-live-authority.test.ts` — 예외를 던지는 `kind` getter가 인증 경계를 빠져나갔고, 인증 장애를 `NETWORK_FAILURE`로 보고했다. 이제 적대적인 credential 모양 9가지가 fetch 0회로 `AUTH_INTEGRATION_FAILURE`로 닫히고, 각 필드는 정확히 한 번만 읽는다. |
| NS-02 | `PARTIAL` | `FIXED` | `tests/unit/contract-registry-immutability.test.ts` — 검증에는 `10_000`, 복사에는 `999_999`를 답한 정책이 두 번째 값으로 설치됐다. 이제 조립 단계가 먼저 snapshot하므로 상한을 넘는 값은 거부한다. |
| NS-03 | `PARTIAL` | `FIXED` | `tests/integration/http-execution-v3-live-authority.test.ts` — `NONE` probe가 deadline 뒤에 `body.locked === true`를 남겼다. 이제 reader를 한 번 취소하고 lock을 푼다. |
| NS-04 | `PARTIAL` | `FIXED` | `tests/unit/opfs-byte-store.test.ts` — 실패한 `journal.complete`가 여전히 `SUCCEEDED` telemetry와 함께 단순 성공을 돌려줬다. 이제 `RECONCILE` 실패를 돌려주고 그 journal 행을 `COMMITTED`로 두며, 끝나지 않은 삭제는 `DEGRADED`로 관찰한다. |
| NS-05 | `PARTIAL` | `FIXED` | `tests/unit/opfs-worker-runtime.test.ts` — bootstrap 실패가 모든 요청에 kind `CAPABILITIES`로 답해서, gateway가 `BLOCKED`를 `UNSUPPORTED`로 바꿨다. 이제 kind 12가지가 다 자기 요청과의 대응(correlation)을 그대로 주고받는다. |
| NS-06 | `PARTIAL` | `FIXED` | 같은 테스트 파일 — 예외를 던지는 `requestId` getter가 RPC timeout을 냈고, 상태를 가진 trap이 공개 promise를 영원히 pending으로 남겼다. 이제 대기 행을 풀기 전에 응답을 디코딩하고, 대응시킬 수 없는 응답이 오면 channel을 닫힌 쪽으로 실패시킨다. |
| NS-07 | `NEW` | `FIXED` | `tests/unit/cursor-pagination-runtime.test.ts` — 생성 뒤에 `maxPages`를 올리자 검증된 상한이 1 page에서 3 page로 넓어졌다. 이제 상한과 협력 객체는 한 번만 잡는다. |
| NS-08 | `NEW` | `FIXED` | `tests/unit/public-response-cache.test.ts` — 협조하지 않는 fetch가 mutation lock을 영원히 붙잡았고, abort 뒤에 끝난 digest가 여전히 asset과 activation marker를 썼다. 이제 terminal owner 하나가 staging 본문 전체를 맡는다. |
| RPC-01 | `PARTIAL` | `FIXED` | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` — reject하거나, 예외를 던지거나, promise가 아닌 `waitClosed()`를 성공으로 흡수했고, 두 번째 실제 stream이 열렸다. 이제 계약 모양에 맞는 receipt가 fulfilled일 때만 등록을 정리한다. |
| RPC-02 | `PARTIAL` | `FIXED` | 같은 테스트 파일 — 예외를 던지는 iterator `return` accessor가 선택된 timeout을 네이티브 `TypeError`로 바꿨고, export된 lease decoder가 적대적인 `Symbol.asyncIterator`에서 예외를 던졌다. |
| RPC-03 | `PARTIAL` | `FIXED` | 같은 테스트 파일 — 검증 중에 registry accessor가 두 번 실행됐고, prototype이나 열거되지 않는 키 뒤에 필드를 숨긴 행이 설치됐다. 이제 모든 registry를 검증 전에 snapshot한다. |
| RPC-04 | `PARTIAL` | `FIXED` | 같은 테스트 파일 — 자기 필드 `{ok,message,encodedBytes}`에 prototype의 `injected`가 더해진 값이 성공이었고, 빠진 `message`가 `undefined`로 느슨한 schema에 닿았다. |
| RT-01 | `PARTIAL` | `FIXED` | `tests/unit/realtime/stream-coordinator.test.ts` — 자기 호출 안에서 `close()`에 다시 들어간 authority가, effect가 아직 pending인데 `{ok:true}`를 받았다. 이제 협력 객체를 부르기 전에 작업을 등록한다. |
| RT-02 | `NEW` | `FIXED` | 같은 테스트 파일 — 예외를 던지는 `scheduleTimeout`이 도는 중인 apply와 겹치는 recovery를 시작했고, `close()`가 네이티브 `TypeError`로 reject했다. 이제 설치할 수 없는 deadline은 result 계약 안에서 fail-closed로 실패한다. |
| TR-01 | `PARTIAL` | `FIXED` | `tests/unit/presigned-transfer.test.ts` — 상태를 가진 issuer가 금지 헤더 검사에는 허용된 헤더 집합을 보여 주고 `Authorization`을 저장할 수 있었다. 이제 등록 값과 그 안에 든 모든 것을 검증 전에 snapshot한다. |
| TR-02 | `PARTIAL` | `FIXED` | `tests/unit/presigned-transfer-delivery.test.ts` — abort 뒤에 resolve된 source lease를 한 번도 닫지 않았다. 이제 holder의 close-once latch를 같이 쓰는 compensator가 정확히 한 번 닫는다. |
| TR-03 | `PARTIAL` | `FIXED` | `tests/unit/abortable-operation.test.ts`, `tests/unit/image-cdn-browser-probe.test.ts`, `tests/unit/resumable-upload-fetch-transport.test.ts` — 결과가 코드에 박힌 microtask 4개 drain에 달려 있었고, 예외를 던지는 scheduler가 호출자 listener를 남긴 채 `probe()`/`execute()`를 네이티브 예외로 reject했다. 이제 primitive는 관찰 순서대로 한 번만 끝나고, 소비자 네 곳이 다 생성 시점에 묶은 timer snapshot과 함께 이 primitive를 쓴다. |
| TR-04 | `PARTIAL` | `FIXED` | `tests/unit/resumable-upload-runtime-teardown.test.ts` — attempt deadline보다 오래 산 provider 때문에 `dispose()`가 drain이 끝난 runtime을 보고하고 checkpoint store를 닫았다. 이제 가공하지 않은 provider 작업은 따로 registry를 두고, 두 registry가 다 멈춰야 한다. |
| TR-05 | `PARTIAL` | `FIXED` | `tests/unit/resumable-upload-http-control-plane.test.ts` — 상태를 가진 `sessionId`가 정규식을 통과한 뒤 `../../unsafe`를 돌려줬다. 이제 decoder는 정확히 한 번 읽어 둔 자기 snapshot을 검증한다. |
| SW-01 | `PARTIAL` | `FIXED` | `tests/unit/service-worker-runtime.test.ts` — 257바이트 상한과 비교하기 전에 1 MiB chunk 하나를 통째로 붙잡았고, 크기 초과가 선언돼도 body를 연 채로 두었으며, reader lock을 끝내 풀지 않았다. |
| SW-02 | `PARTIAL` | `FIXED` | `tests/unit/service-worker-web-push-remediation.test.ts` — generator가 `/assets/bad@name-abcdefgh.js`를 내보냈고, decoder가 방금 만든 manifest를 거부했다. 이제 둘이 canonical 경로 판정 함수 하나를 같이 쓰고, generator가 자기 출력을 스스로 검증한다. |
| WP-01 | `PARTIAL` | `FIXED` | `tests/unit/web-push-worker-runtime.test.ts` — 평범한 click을 두 번 셌고, 늦은 rejection이 `MAYBE_APPLIED`를 `NOT_APPLIED`로 낮췄으며, 늦은 관찰이 `waitUntil` 밖에서 돌았다. |
| GOV-03 | `OPEN` | `FIXED` | `scripts/check-remediation-ledger.ts` — 처리 결과와 증거 경로를 기계가 읽을 수 있고, 열린 행이 하나라도 있으면 일괄 종료 문장을 막는다. |
| GOV-04 | `OPEN` | `FIXED` | `scripts/check-adapter-inventory.ts` — 게이트가 importer 하나만 있어도 통과했다. 이제 이름을 밝힌 소비자 네 곳이 import를 공유 primitive로 해석해야 하고, 정확한 집합을 출력한다. |
| GOV-05 | `OPEN` | `FIXED` | `config/recipes/frontend-capability-recipes.json` — 아래 budget 메모를 본다. |
### The file-transfer bundle budget
### file-transfer 번들 budget
`check:optional-recipes:source` failed at the previous baseline too (52,078 >
52,000 gzip bytes), so it was not green before this work either. Duplicate abort
and deadline mechanics were consolidated first: the Image probe and the Resumable
fetch transport now use the shared `abortable-operation` primitive instead of
their own scopes, and four decoders share `src/contracts/exact-snapshot.ts`
rather than each carrying its own descriptor walk. The remainder is the
correctness code the third re-review asked for — exact decoders, late-value
compensators and physical-work registries — so the budget is reset to **54,600**
gzip bytes against a measured **53,810**, rather than the failure being carried
forward as if it were green.
`check:optional-recipes:source`는 이전 기준에서도 실패했다(52,078 > 52,000 gzip 바이트). 그러니 이 작업 전에도 통과 상태가 아니었다. 먼저 중복된 abort·deadline 메커니즘을 합쳤다. Image probe와 Resumable fetch transport는 이제 자기 scope 대신 공유 `abortable-operation` primitive를 쓴다. decoder 네 개는 각자 descriptor를 훑지 않고 `src/contracts/exact-snapshot.ts`를 같이 쓴다. 남은 크기는 세 번째 재검토가 요구한 정확성 코드다. exact decoder, 늦은 값 compensator, physical-work registry가 그것이다. 그래서 실패를 통과인 척 끌고 가지 않고, budget을 측정값 **53,810**에 맞춰 **54,600** gzip 바이트로 다시 정했다.
The budget has since moved with later fixes. On 2026-11-03 it was set to
**57,800** gzip bytes against a measured **56,053** (measured + 3%, rounded up
to 100 B). The rule and the current values are in
`docs/architecture/optional-adapter-recipes.md`.
그 뒤 수정이 이어지면서 budget도 바뀌었다. 2026-11-03에 측정값 **56,053**에 맞춰 **57,800** gzip 바이트로 정했다(측정값 + 3%, 100 B 단위로 올림). 규칙과 지금 값은 `docs/architecture/optional-adapter-recipes.md`에 있다.
### Regenerated evidence (this commit)
### 다시 만든 증거 (이 커밋)
| Command | Exit | Result |
| 명령 | 종료 | 결과 |
| --- | ---: | --- |
| `corepack pnpm check:types` | 0 | all six projects pass |
| `corepack pnpm check:architecture` | 0 | 290 modules, 879 dependencies; 12 fixtures PASS; allowed PASS / 9 forbidden rejected |
| `corepack pnpm check:adapter-inventory` | 0 | 119 files; 7 shared extensions; 5 shared-abort importers listed |
| `corepack pnpm check:optional-recipes:source` | 0 | file-transfer 53,810 / 54,600 gzip bytes |
| `corepack pnpm exec vitest run tests/unit/browser-rpc tests/unit/realtime` | 0 | 17 files / 234 passed |
| abortable-operation, presigned, resumable, image CDN | 0 | 7 files / 176 passed |
| OPFS, journal, public cache, cursor | 0 | 5 files / 100 passed |
| Service Worker + Web Push | 0 | 6 files / 79 passed |
| `corepack pnpm exec vitest run tests/integration` | 0 | 11 files / 82 passed |
| `corepack pnpm check:types` | 0 | 여섯 프로젝트 모두 통과 |
| `corepack pnpm check:architecture` | 0 | 모듈 290개, 의존 879개. fixture 12개 PASS. 허용 PASS / 금지 9개 거부 |
| `corepack pnpm check:adapter-inventory` | 0 | 파일 119개. 공유 확장자 7개. shared-abort importer 5개 나열 |
| `corepack pnpm check:optional-recipes:source` | 0 | file-transfer 53,810 / 54,600 gzip 바이트 |
| `corepack pnpm exec vitest run tests/unit/browser-rpc tests/unit/realtime` | 0 | 파일 17개 / 234개 통과 |
| abortable-operation, presigned, 재개 가능 업로드, image CDN | 0 | 파일 7개 / 176개 통과 |
| OPFS, journal, 공개 캐시, cursor | 0 | 파일 5개 / 100개 통과 |
| Service Worker + Web Push | 0 | 파일 6개 / 79개 통과 |
| `corepack pnpm exec vitest run tests/integration` | 0 | 파일 11개 / 82개 통과 |
The full `tests/unit` + `tests/integration` run is **1,845 passed / 1,864**,
128 of 129 files green. Every one of the 19 failures is in
`tests/system/ci-runner/ci-artifact-contract.test.ts` and is the pre-existing sandbox,
cgroup, RLIMIT and `/tmp` permission behaviour already recorded above — the same
file failed identically before this work. No adapter test fails.
전체 `tests/unit` + `tests/integration` 실행은 **1,845개 통과 / 1,864개**이고, 파일 129개 중 128개가 통과했다. 실패 19건은 전부 `tests/system/ci-runner/ci-artifact-contract.test.ts`에서 나온다. 위에 이미 적은, 원래 있던 sandbox, cgroup, RLIMIT, `/tmp` 권한 동작이다. 이 작업 전에도 같은 파일이 똑같이 실패했다. 실패하는 adapter 테스트는 없다.
## Operational contract review (2026-08-15)
## 운영 계약 리뷰 (2026-08-15)
A fourth review looked past the adapter layer at the operational contract:
feature on/off, environment separation, folder boundaries, and which gates were
actually green. It found five red gates and three structural gaps. Every row
below names the defect, not the symptom.
네 번째 리뷰는 adapter 층을 넘어 운영 계약을 봤다. feature 켜고 끄기, 환경 분리, 폴더 경계, 그리고 실제로 통과한 게이트가 무엇인지다. 실패하는 게이트 다섯과 구조 빈틈 셋을 찾았다. 아래 각 행은 증상이 아니라 결함을 적는다.
| id | area | disposition | what was actually wrong |
| id | 영역 | 처리 | 실제로 잘못된 것 |
| --- | --- | --- | --- |
| `OPS-01` | release | `FIXED` | `public/` is copied verbatim into `dist/`, so every build — production included — shipped the local runtime document. Runtime config now comes from `config/runtime/<profile>.json`. |
| `OPS-02` | release | `FIXED` | Release coherence proved the artifacts agreed with each other, never that they belonged in production. `FE-GATE-027` refuses an artifact whose `APP_ENV`, auth mode, endpoints or build identity do not match a declared `RELEASE_TARGET`, and refuses an undeclared target outright. |
| `OPS-03` | runtime | `FIXED` | `REQUEST_TIMEOUT_MS` was validated and then never passed to the V3 executor; every operation ran on its contract's own deadline. It is now a ceiling that may tighten a contract, never loosen one. |
| `OPS-04` | build | `FIXED` | `VITE_ROUTER_BASE_PATH` drove the router and the Service Worker scope but not Vite's asset `base`, so a sub-path deployment emitted root-absolute assets. One value now feeds all three. |
| `OPS-05` | provider | `FIXED` | bubblewrap 0.9.0 drops whatever follows the option stream inside an `--args` file, so the sandboxed command was never executed: bwrap printed usage and exited 1. Options stay hidden; the command travels on real argv. |
| `OPS-06` | provider | `FIXED` | The scope wrapper read its liveness pipe through `fs`, a blocking `read(2)` on a pipe the supervisor never closes. `process.exit` deadlocked joining that thread, so a completed provider was reported as a timeout kill. |
| `OPS-07` | release | `FIXED` | `mkdir`/`open` modes were left to the ambient umask, so a hardened runner produced directories it could not enter and handed `tar` a file it could not re-open. |
| `OPS-08` | release | `FIXED` | Promotion cleanup deleted this promotion's exact five through a pinned descriptor and only then noticed the leaf had been substituted, leaving a half-emptied directory a retry could not distinguish from a completed one. |
| `OPS-09` | removability | `FIXED` | The removal fixture was not a repository, had no `.gitignore`, and each removal script kept its own copy-target list that had drifted. Supply-chain generation therefore failed inside every fixture and took the whole provider suite down with it. |
| `OPS-10` | removability | `FIXED` | A platform integration file asserted the reference feature's route ids, so removing the feature left it importing a deleted module. The assertion moved to the feature's own test tree. |
| `OPS-11` | removability | `FIXED` | A removal fixture runs against a deliberately reduced CI contract; the canonical exact-count tests re-imposed the full authority on it and failed the fixture for the reduction it exists to prove. |
| `OPS-12` | browser | `FIXED` | Four browser-capability specs answered capability requests without the `protocol` field the hardened envelope requires, so every capability was refused and the download and part-upload paths asserted against an empty transcript. |
| `OPS-13` | browser | `FIXED` | A refused capability document answered `recovery: NONE`, contradicting both the design record and the vault, which already answers `REISSUE_CAPABILITY`. |
| `OPS-14` | performance | `FIXED` | Playwright matches accessible names by substring, so the navigation entry matched the home page's call to action too; the run died on a strict-mode violation before the first measurement and produced no evidence at all. |
| `OPS-15` | visual | `FIXED` | The platform overview baseline predated the reference routes moving from `integration-defined` to `session-required`, so the only visual gate covering that page failed for its own staleness. |
| `OPS-16` | architecture | `FIXED` | `src/contracts` imported `src/application` for the shared `Result` and the compatibility predicate; neither package owned the shared vocabulary. Both moved down to contracts. |
| `OPS-17` | architecture | `FIXED` | The documented "no adapter depends on another concrete adapter" rule had no executable form, and `diagnostics` imported a guard out of `telemetry`. The guard moved to the adapter kernel and the rule is now enforced with a same-directory backreference. |
| `OPS-18` | architecture | `PARTIAL` | Generic presentation still reads the installed-feature registries. The rule freezes the exact set of modules doing so today; a new edge fails. Lifting the assembly into `bootstrap` is not done. |
| `OPS-19` | documentation | `FIXED` | README and the manual accessibility checklist both claimed six routes while ten were registered, leaving four screens outside the declared manual review scope. The list is now derived from the route registry by `verify:documentation`. |
| `OPS-01` | release | `FIXED` | `public/`은 `dist/`로 그대로 복사된다. 그래서 production을 포함한 모든 빌드가 local runtime 문서를 함께 내보냈다. 이제 runtime 설정은 `config/runtime/<profile>.json`에서 온다. |
| `OPS-02` | release | `FIXED` | release 일관성 검사는 산출물끼리 맞는지만 증명했고, 그 산출물이 production에 맞는지는 증명하지 않았다. `FE-GATE-027`은 `APP_ENV`, 인증 모드, endpoint, 빌드 식별자가 선언된 `RELEASE_TARGET`과 맞지 않는 산출물을 거부하고, 선언되지 않은 target은 아예 거부한다. |
| `OPS-03` | runtime | `FIXED` | `REQUEST_TIMEOUT_MS`는 검증만 하고 V3 executor에 넘기지 않았다. 그래서 모든 작업이 자기 계약의 deadline으로 돌았다. 이제 이 값은 상한이다. 계약을 조일 수는 있지만 풀 수는 없다. |
| `OPS-04` | 빌드 | `FIXED` | `VITE_ROUTER_BASE_PATH`는 router와 Service Worker scope는 정했지만 Vite의 asset `base`는 정하지 않았다. 그래서 하위 경로 배포가 root 기준 절대 경로 asset을 내보냈다. 이제 값 하나가 셋 모두에 들어간다. |
| `OPS-05` | provider | `FIXED` | bubblewrap 0.9.0은 `--args` 파일 안에서 option stream 뒤에 오는 것을 버린다. 그래서 sandbox 안 명령이 한 번도 실행되지 않았다. bwrap은 usage를 찍고 1로 끝났다. 이제 option은 그대로 숨기고, 명령은 진짜 argv로 넘긴다. |
| `OPS-06` | provider | `FIXED` | scope wrapper가 liveness pipe를 `fs`로 읽었다. supervisor가 끝내 닫지 않는 pipe에 대한 blocking `read(2)`다. `process.exit`이 그 thread를 join하다 교착에 빠져서, 끝난 provider를 timeout kill로 보고했다. |
| `OPS-07` | release | `FIXED` | `mkdir`/`open` mode를 주변 umask에 맡겼다. 그래서 강화된(hardened) runner가 자기가 들어갈 수 없는 디렉터리를 만들고, 다시 열 수 없는 파일을 `tar`에 넘겼다. |
| `OPS-08` | release | `FIXED` | promotion 정리가 고정한 descriptor로 이번 promotion의 파일 정확히 다섯 개를 지운 뒤에야 leaf가 바꿔치기된 것을 알아챘다. 그래서 절반만 빈 디렉터리가 남았고, 재시도는 그것을 끝난 디렉터리와 구별하지 못했다. |
| `OPS-09` | 제거 가능성 | `FIXED` | 제거 fixture는 저장소가 아니었고 `.gitignore`도 없었다. 제거 스크립트마다 따로 복사 대상 목록을 들고 있었고, 그 목록들이 서로 어긋났다. 그래서 supply-chain 생성이 모든 fixture 안에서 실패했고, provider 테스트 전체를 함께 무너뜨렸다. |
| `OPS-10` | 제거 가능성 | `FIXED` | platform integration 파일이 참조 feature의 route id를 단언했다. 그래서 그 feature를 지우면 이 파일이 지운 모듈을 import하는 상태로 남았다. 단언은 feature 자신의 테스트 트리로 옮겼다. |
| `OPS-11` | 제거 가능성 | `FIXED` | 제거 fixture는 일부러 줄인 CI 계약으로 돈다. 정본 exact-count 테스트가 그 fixture에 전체 기준을 다시 들이대서, fixture가 증명하려고 존재하는 바로 그 축소 때문에 fixture를 실패시켰다. |
| `OPS-12` | 브라우저 | `FIXED` | browser-capability spec 네 개가 강화된 envelope가 요구하는 `protocol` 필드 없이 capability 요청에 답했다. 그래서 모든 capability가 거부됐고, download와 part-upload 경로는 빈 기록을 두고 단언했다. |
| `OPS-13` | 브라우저 | `FIXED` | 거부된 capability 문서가 `recovery: NONE`으로 답했다. 이는 설계 기록과도, 이미 `REISSUE_CAPABILITY`로 답하는 vault와도 어긋난다. |
| `OPS-14` | 성능 | `FIXED` | Playwright는 accessible name을 부분 문자열로 맞춘다. 그래서 navigation 항목이 home page의 call to action 버튼과도 맞았다. 실행은 첫 측정 전에 strict-mode 위반으로 죽었고, 증거를 하나도 남기지 않았다. |
| `OPS-15` | 시각(visual) | `FIXED` | platform overview 기준 이미지는 참조 route가 `integration-defined`에서 `session-required`로 바뀌기 전에 만든 것이었다. 그래서 그 page를 다루는 유일한 visual 게이트가 자기 기준이 낡아서 실패했다. |
| `OPS-16` | 아키텍처 | `FIXED` | `src/contracts`가 공유 `Result`와 호환성 판정 함수를 쓰려고 `src/application`을 import했다. 어느 쪽도 공유 어휘의 owner가 아니었다. 둘 다 contracts로 내렸다. |
| `OPS-17` | 아키텍처 | `FIXED` | 문서에 적힌 "어떤 adapter도 다른 구체 adapter에 의존하지 않는다" 규칙은 실행 가능한 형태가 없었다. 그리고 `diagnostics`가 `telemetry`에서 guard를 import했다. guard는 adapter kernel로 옮겼고, 이제 같은 디렉터리 역참조(backreference)로 규칙을 강제한다. |
| `OPS-18` | 아키텍처 | `PARTIAL` | 범용 presentation이 아직 installed-feature registry를 읽는다. 규칙은 지금 그렇게 하는 모듈 집합을 정확히 고정한다. 새 의존 edge는 실패한다. 조립을 `bootstrap`으로 올리는 일은 하지 않았다. |
| `OPS-19` | 문서 | `FIXED` | README와 수동 접근성 체크리스트는 둘 다 route 6개라고 했지만, 등록된 것은 10개였다. 그래서 화면 4개가 선언된 수동 리뷰 범위 밖에 있었다. 이제 `verify:documentation`이 route registry에서 목록을 끌어낸다. |
### Product feature selection (2026-08-15, second pass)
### 제품 feature 선택 (2026-08-15, 2차 작업)
| id | disposition | what changed |
| id | 처리 | 바뀐 것 |
| --- | --- | --- |
| `OPS-20` | `FIXED` | Which features a build contains is now a declared manifest rather than five registries spreading a literal. `VITE_PRODUCT_FEATURES` narrows it at build time; a test fails if a new registry forgets to consult it. |
| `OPS-21` | `FIXED` | `FEATURE_OVERRIDES` in the runtime document takes an installed feature out of service without a rebuild. The router refuses its routes, not just the navigation, so a typed deep link cannot still mount it. |
| `OPS-22` | `FIXED` | Both inputs are subtractive by vocabulary: the override enum has no `ENABLED`, and a build-time selection naming a feature the source tree does not declare is refused rather than ignored. |
| `OPS-23` | `FIXED` | A sandbox that fails to launch now reports why. The supervisor consumed the child's output only to enforce a byte cap and discarded it, so a host restriction surfaced as an unexplained `exit=1`. Lines the sandbox tooling itself emits are kept; provider output is still discarded. |
| `OPS-20` | `FIXED` | 빌드에 어떤 feature가 들어가는지를, 이제 리터럴을 퍼뜨린 registry 다섯 개가 아니라 선언된 manifest가 정한다. `VITE_PRODUCT_FEATURES`가 빌드 때 그 범위를 좁힌다. 새 registry가 이 값을 확인하지 않으면 테스트가 실패한다. |
| `OPS-21` | `FIXED` | runtime 문서의 `FEATURE_OVERRIDES`는 다시 빌드하지 않고 설치된 feature를 서비스에서 뺀다. router는 navigation만 숨기지 않고 그 feature의 route를 거부한다. 그래서 주소를 직접 쳐서 들어온 deep link도 그 feature를 띄울 수 없다. |
| `OPS-22` | `FIXED` | 두 입력 다 어휘부터 빼기만 할 수 있다. override enum에는 `ENABLED`가 없다. 소스 트리가 선언하지 않은 feature를 적은 빌드 시점 선택은 무시하지 않고 거부한다. |
| `OPS-23` | `FIXED` | 실행에 실패한 sandbox가 이제 이유를 보고한다. supervisor는 바이트 상한을 지키려고만 자식 출력을 읽고 버렸다. 그래서 host 제약이 설명 없는 `exit=1`로만 드러났다. sandbox 도구가 직접 내는 줄은 남긴다. provider 출력은 여전히 버린다. |
An env var does **not** shrink the bundle, and the code says so. A static import
cannot be undone by a value, and making the import graph depend on a
configuration string is what §3.5 exists to prevent. Measured: `none` changes
the output by 58 bytes. Physical removal is FE-GATE-020's job.
환경 변수는 번들을 줄이지 **않는다**. 코드도 그렇게 적는다. 정적 import는 값으로 되돌릴 수 없다. import graph가 설정 문자열에 따라 달라지게 하는 것은 §3.5가 막으려는 바로 그 일이다. 측정 결과 `none`은 출력을 58바이트 바꾼다. 물리적 제거는 FE-GATE-020이 맡는다.
### Host restriction discovered during this pass
### 이 작업 중에 발견한 host 제약
`bwrap --unshare-net` no longer works on this machine:
이 기계에서는 `bwrap --unshare-net`이 더는 동작하지 않는다:
```
$ printf '%s\0' --unshare-net --ro-bind /usr /usr ... | bwrap --args 3 -- /bin/true
@@ -539,52 +460,31 @@ $ sysctl kernel.apparmor_restrict_unprivileged_userns
kernel.apparmor_restrict_unprivileged_userns = 1
```
That reproduction contains none of this repository's code. Earlier in the same
session the identical sandbox ran to completion, so the restriction became
active partway through. While it holds, 16 of the 108 provider tests cannot run
here — they need a sandbox the kernel will not grant. They are not counted as
green and not counted as product defects; under a host that permits the
namespace the same file was 107/108.
이 재현에는 이 저장소의 코드가 하나도 없다. 같은 세션 앞부분에서는 똑같은 sandbox가 끝까지 돌았다. 그러니 제약은 도중에 켜졌다. 제약이 있는 동안 provider 테스트 108개 중 16개는 여기서 돌 수 없다. kernel이 허락하지 않는 sandbox가 필요하기 때문이다. 이 테스트는 통과로도, 제품 결함으로도 세지 않는다. namespace를 허락하는 host에서는 같은 파일이 107/108이었다.
### Still red after this pass
### 이 작업 뒤에도 실패하는 것
*applies effective aggregate cgroup limits without exposing command or
credentials* was rewritten. It used to read the live process tree with one
`ps` per pid and assert mid-run, which lost a race against a sandbox that now
completes in a few hundred milliseconds; it records the tree from `/proc` every
5ms and asserts on the recording after the run. That restructuring is also what
revealed the host restriction above — the supervisor had been failing to launch
the sandbox and the test was dying on the observation first.
*applies effective aggregate cgroup limits without exposing command or credentials* 테스트를 다시 썼다. 전에는 pid마다 `ps`를 한 번씩 돌려 살아 있는 프로세스 트리를 읽고, 실행 도중에 단언했다. 이 방식은 이제 몇백 밀리초 만에 끝나는 sandbox와의 경주에서 졌다. 지금은 `/proc`에서 5ms마다 트리를 기록하고, 실행이 끝난 뒤 그 기록으로 단언한다. 위의 host 제약도 이렇게 구조를 바꾸면서 드러났다. supervisor는 그동안 sandbox를 띄우는 데 실패하고 있었는데, 테스트가 관찰 단계에서 먼저 죽었던 것이다.
Tests that spawn processes, build archives and sign evidence were given a
30s budget instead of the 10s default sized for pure-JS unit tests. The default
was not raised: that would hide a genuinely hung test.
프로세스를 띄우고, archive를 만들고, 증거에 서명하는 테스트에는 순수 JS unit 테스트에 맞춘 기본값 10s 대신 30s budget을 줬다. 기본값은 올리지 않았다. 올리면 정말로 멈춘 테스트를 숨기게 된다.
### FE-GATE-020 after this pass
### 이 작업 뒤 FE-GATE-020
| fixture | before | after |
| fixture | 전 | 후 |
| --- | ---: | ---: |
| reference feature | failed before its first assertion | 1,612 pass / 1 fail |
| optional recipe | 39 failures | 1,386 pass / 2 fail |
| browser file + storage | 40 failures | 1,006 pass / 3 fail |
| realtime | not reached | 1,159 pass / 1 fail |
| 참조 feature | 첫 단언 전에 실패 | 1,612개 통과 / 1개 실패 |
| 선택 recipe | 실패 39개 | 1,386개 통과 / 2개 실패 |
| 브라우저 파일 + 스토리지 | 실패 40개 | 1,006개 통과 / 3개 실패 |
| realtime | 도달 못 함 | 1,159개 통과 / 1개 실패 |
Every remaining failure is one of the three environment-limited tests above.
남은 실패는 하나하나가 위에서 말한 환경 제약 테스트 세 개 중 하나다.
Lab performance now produces evidence, and that evidence shows the
named-interaction budget missed on this machine (367–724ms against 200ms). The
metric measures a full lazy-route navigation while the budget is an
INP-shaped 200ms, so the two do not describe the same thing. No budget was
changed to make this green.
Lab 성능 측정이 이제 증거를 낸다. 그 증거는 이 기계에서 named-interaction budget을 넘었음을 보여 준다(200ms 기준에 367–724ms). 이 지표는 lazy route 이동 전체를 재는데, budget은 INP 모양의 200ms다. 그래서 둘은 같은 것을 말하지 않는다. 이를 통과로 만들려고 budget을 바꾸지 않았다.
WebKit remains unavailable in this environment (`libevent-2.1-7t64`,
`libavif16` are not installed), so 14 browser-capability specs and the WebKit
E2E project are unverified here. Chromium and Firefox are 28/28 and visual is
5/5.
이 환경에서는 여전히 WebKit을 쓸 수 없다(`libevent-2.1-7t64`, `libavif16`이 설치되지 않았다). 그래서 browser-capability spec 14개와 WebKit E2E project는 여기서 확인하지 못했다. Chromium과 Firefox는 28/28, visual은 5/5다.
## Rules for updating this ledger
## 이 원장을 고치는 규칙
- A row moves out of `NOT_STARTED` only with a linked red test, its green run, and the commit id.
- `PROMOTION_BLOCKED` rows never become `DEFECT`; they close through an authorized product
selection change with the browser/provider evidence named in the plan.
- Environmental gate failures are copied verbatim and are never claimed as green.
- 행은 연결된 실패 테스트, 그 테스트의 통과 실행, 커밋 id가 있을 때만 `NOT_STARTED`에서 벗어난다.
- `PROMOTION_BLOCKED` 행은 `DEFECT`가 되지 않는다. 승인된 제품 선택 변경과, 계획이 정한 browser/provider 증거가 있을 때 닫힌다.
- 환경 탓 게이트 실패는 원문 그대로 옮기고, 절대 통과로 주장하지 않는다.
@@ -12,7 +12,7 @@
## 1. 적용 범위
현재 reference REST → Schema → Mapper → TanStack Query vertical은 V3 contract
현재 참조 구현(reference)의 REST → Schema → Mapper → TanStack Query 수직 흐름(vertical)은 V3 contract
executor(`src/adapters/http/http-execution-v3.ts`)로 `COMPOSED`다. 조합 위치는
`src/bootstrap/runtime-adapters.ts`의 `createContractHttpExecutor`다. 이 문서의
"current v1"은 V2 client 시절에 쓴 말이다. V2 client는 2026-11-03에 지웠다.
@@ -54,10 +54,10 @@ PromotionEvidence
| control | current v1 | target v2 |
| --- | --- | --- |
| operation traffic switch | 없음 | provider/family/operation별 `TrafficAdmission` |
| frontend containment | promotion 중지와 known-good release rollback; feature composition 변경은 재배포 필요 | atomic admission disable |
| frontend containment | 승격(promotion) 중지와 정상으로 확인된(known-good) release로 rollback. feature 조합을 바꾸려면 재배포가 필요 | admission을 원자적으로 끄기 |
| provider containment | actual BFF/API owner의 route/kill switch가 있을 때만 사용 | registered provider kill switch와 probe |
| query cleanup | composed QueryClient/coordinator의 cancel·invalidate·local clear | generation fence와 profile-scoped cleanup |
| mutation recovery | backend 상태/idempotency owner와 수동 reconcile | effect certainty + runtime/scope coordinator |
| query cleanup | 조립된 QueryClient/coordinator의 취소·무효화·로컬 삭제 | generation fence와 profile 범위 정리 |
| mutation recovery | backend 상태/idempotency owner와 수동으로 맞추기(reconcile) | 효과 확실성(effect certainty)과 runtime/scope coordinator |
따라서 current v1 incident에서 존재하지 않는 switch를 내렸다고 기록하지 않는다.
target v2가 composed된 operation만 `TrafficAdmission`을 먼저 내린다. 그 전에는
@@ -78,7 +78,7 @@ current v1으로의 fallback은 (1) 해당 operation의 provider/security eviden
- semantic operation/profile/provider ID
- protocol/semantics
- safe failure kind
- HTTP status group, GraphQL safe category, gRPC status bucket
- HTTP status 그룹, GraphQL의 안전한 category, gRPC status bucket
- logical/physical attempt, auth recovery와 deadline bucket
- provider가 측정한 encoded transfer bucket과 browser가 측정한
decoded/result/message/frame/page/item byte/count bucket
@@ -139,11 +139,11 @@ artifact에서 access-controlled하게 비교한다.
| 증상 | 우선 확인 |
| --- | --- |
| 특정 release에서 전 operation 실패 | runtime config, provider endpoint, auth owner, contract set |
| schema/mapper mismatch 급증 | backend artifact rollout, unknown/null/enum/scalar 변화, wrong codec |
| 특정 release에서 전 operation 실패 | runtime config, provider endpoint, 인증(auth) owner, contract 묶음 |
| schema/mapper 불일치 급증 | backend 산출물 배포(rollout), unknown/null/enum/scalar 변화, 잘못된 codec |
| retry/traffic 폭증 | retry owner 중복, 401 loop, Retry-After, total deadline |
| stale/wrong account data | scope generation, late result, query key collision, invalidation |
| command duplicate/rollback 이상 | idempotency tuple, input-aware concurrency, optimistic revision |
| 낡거나 잘못된 account 데이터 | scope generation, 늦게 온 결과, query key 충돌, 무효화(invalidation) |
| command 중복/rollback 이상 | idempotency tuple, 입력을 고려한(input-aware) 동시성 제어, 낙관적(optimistic) revision |
| list가 반복/무한 증가 | cursor loop/snapshot/page/item/byte ceiling |
| provider 200인데 client 실패 | status/media/envelope/schema/mapper/body cap |
| 로그에서 payload/ID 발견 | redaction/allowlist bypass, diagnostics producer |
@@ -235,8 +235,8 @@ diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그
byte cap을 확인한다.
3. actual encoded transfer/decompression ratio cap은 BFF/proxy/CDN evidence에서
확인한다. browser reader가 encoded bytes를 셌다고 가정하지 않는다.
4. standard JSON parse profile이면 decoded byte는 pre-parse guard,
depth/node/key는 post-parse admission guard인지 확인한다.
4. 표준 JSON parse profile이면 decoded byte는 parse 전(pre-parse) guard,
depth/node/key는 parse 뒤(post-parse) admission guard인지 확인한다.
5. truncated, content encoding/decompression overflow와 invalid UTF-8을 구분한다.
6. success status/media/envelope profile이 operation registry와 일치하는지 확인한다.
7. schema unknown-field policy와 actual codec fingerprint를 확인한다.
@@ -369,8 +369,8 @@ terminal completeness 전 staging을 complete query cache로 commit하지 않는
확인한다. official runtime이면 runtime-owned callback/status API와
`ClientReadableStream.cancel()` 경로를 확인하며 raw `ReadableStream` parser가
있다고 가정하지 않는다.
4. body trailer frame 또는 zero-body trailers-only response header 중 terminal
status source가 정확히 하나인지 확인한다.
4. 최종 status를 알려 주는 곳(terminal status source)이 정확히 하나인지 확인한다. 후보는
body trailer frame과, body가 없는 trailers-only 응답의 header다.
5. `grpc-status`가 있으면 canonical decimal `0..16`으로 exactly once인지, body
trailer name lowercase와 rich-details outer code가 맞는지 확인하며 그 status를
authority로 사용한다.
@@ -380,7 +380,7 @@ terminal completeness 전 staging을 complete query cache로 commit하지 않는
이것을 wire header로 위조하지 않고 internal normalized failure로만 사용한다.
7. HTTP success만으로 RPC success를 기록하지 않는다. duplicate/conflicting/
malformed terminal source는 provider incompatibility로 traffic을 닫는다.
8. Envoy의 upstream HTTP/2, filter order, route/idle/max-stream timeout과 buffering
8. Envoy의 upstream HTTP/2, filter 순서, route/idle/max-stream timeout과 buffering
profile을 확인한다. default route timeout으로 long stream이 잘렸는지 확인한다.
9. raw grpc-message/status-details를 ticket에 복사하지 않는다.
@@ -400,8 +400,8 @@ terminal completeness 전 staging을 complete query cache로 commit하지 않는
3. duplicate/order/gap/resume token protocol을 확인한다.
4. event 전달 뒤 transport-only auto replay가 없었는지 확인한다.
5. overflow/gap/truncation에서 current aggregate를 complete success로 쓰지 않는다.
6. finite aggregate는 valid OK terminal status/completeness 뒤 atomic cache
commit인지 확인한다.
6. 끝이 있는(finite) aggregate는 올바른 OK 최종 status와 완결성(completeness)을 확인한 뒤
cache에 원자적으로 commit하는지 확인한다.
7. actual proxy buffering/flush와 affected browser cohort를 확인한다.
### 8.4 Proxy/CORS
@@ -426,8 +426,8 @@ actual proxy를 복구한다. client decoder를 느슨하게 만들어 provider
1. exact Connect-Web package/runtime, `CONNECT | GRPC_WEB`, JSON/binary,
POST/GET와 rpc kind row를 확인한다. content type으로 다른 protocol을 자동
선택하지 않는다.
2. Connect unary는 HTTP status + bounded Connect error, stream은 HTTP admission +
exactly-one final EndStream을 각각 authority로 사용한다.
2. Connect unary는 HTTP status와 크기 상한이 있는 Connect error를, stream은 HTTP admission과
정확히 하나인 마지막 EndStream을 각각 authority로 사용한다.
3. missing/early/duplicate EndStream, terminal 뒤 data, malformed/oversize
envelope와 compression mismatch에서 call을 cancel하고 cache write를 막는다.
4. stock runtime이 whole unary body를 읽는 profile이면 edge encoded/decompressed
@@ -436,7 +436,7 @@ actual proxy를 복구한다. client decoder를 느슨하게 만들어 provider
5. remaining total deadline이 0 이하면 runtime `timeoutMs=0`을 호출하지 않고
local deadline failure로 닫는다. abort 뒤 command는 backend receipt로
reconcile한다.
6. GET은 descriptor `NO_SIDE_EFFECTS`, input classification, URL cap, cache key,
6. GET은 descriptor `NO_SIDE_EFFECTS`, 입력 분류, URL 상한(cap), cache key,
`Vary`와 credential/preflight profile이 모두 일치하는지 확인한다.
7. raw Connect message/metadata/detail/debug를 ticket에 복사하지 않는다.
@@ -492,7 +492,7 @@ fallback도 old generation을 cancel한 뒤 새 logical query로만 시작한다
### 11.0 Current v1 available checks
1. Query retry off, global stale/gc, AbortSignal과 affected query의
1. Query retry가 꺼져 있는지, 전역 stale/gc, AbortSignal과 영향받은 query의
cancel/invalidate/local clear를 확인한다.
2. current arbitrary key/canonicalize와 hook-local pending Promise를 관측하고
collision/incorrect join cohort cache를 clear한다.
@@ -523,8 +523,8 @@ fallback도 old generation을 cancel한 뒤 새 logical query로만 시작한다
### 11.3 Mutation ordering/rollback — target v2
1. 전체 validated semantic input의 runtime-private exact equality + identity
token이 아닌 hook instance로 join/reject를 판정했는지 확인한다.
1. join/reject를 검증된 semantic input 전체의 runtime-private 정확한 동일성(exact equality)과
identity token이 아니라 hook instance로 판정했는지 확인한다.
2. `JOIN_IDENTICAL | REJECT_DUPLICATE | ALLOW_INDEPENDENT` 결과와 fetch/Promise
횟수가 profile대로인지 확인한다.
3. runtime/scope coordinator에서 same logical key의 two-hook/out-of-order
@@ -600,7 +600,7 @@ revoke/rotate한다. 삭제/보존은 incident response 정책을 따른다.
- idempotency concurrent replay/unknown effect
- cursor loop/ETag 304/412
- GraphQL persisted miss/partial/cost
- gRPC missing/conflicting terminal status source, corrupt frame와 stream gap
- gRPC 최종 status source 누락·충돌, 깨진 frame과 stream gap
- query key collision/account late result
- optimistic concurrent rollback
- kill switch/coherent rollback
@@ -1,14 +1,14 @@
# Browser file and storage recovery runbook
# 브라우저 파일·저장소 복구 runbook
이 runbook은 VD-11 capability를 실제 프로젝트에서 선택한 뒤 사용하는
production 운영 template이다. 현재 skeleton에는 native reference runtime이
`AVAILABLE_NOT_COMPOSED`로 존재하지만 제품 dataset과 bootstrap에는 연결되지
않았으므로 이 문서 자체가 현재 서비스 incident procedure를 활성화하지 않는다.
설치 branch는 owner, dashboard, alert threshold, kill-switch key,
설치 branch는 owner, dashboard, 경보 기준값(alert threshold), kill-switch key,
backend/storage 연락처와 evidence 위치를 채워야 한다.
VD-15가 설계한 origin-wide pressure/GC coordinator, OPFS/Cache forward
migration, OPFS real readiness preflight, bounded Cache cleanup과 preview decode
migration, OPFS 실제 준비 상태 사전 검사(readiness preflight), 상한 있는 Cache 정리와 preview decode
probe는 현재 `DESIGNED_NOT_IMPLEMENTED`다. 아래 절차에서 이 기능을 전제로 한
자동 조치는 해당 runtime이 구현·조합된 제품에서만 실행한다. 현재 reference
primitive를 coordinator 완료 증거로 사용하지 않는다.
@@ -107,8 +107,8 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
| 상황 | 시작 심각도 |
| --- | --- |
| authorization 우회, private/auth response cache, content integrity mismatch | P1 |
| committed user-authored data unreadable/corrupt, widespread migration failure | P1 |
| 권한(authorization) 우회, private/auth 응답 캐시, content 무결성 불일치 | P1 |
| commit된 사용자 작성 data를 읽을 수 없거나 손상됨, 넓게 퍼진 migration 실패 | P1 |
| upload/download 실패 급증, IndexedDB blocked 증가, OPFS reconstructable loss | P2 |
| enhanced picker만 실패하고 baseline 정상 | P3 |
@@ -130,7 +130,7 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
1. 사용자가 실제 취소한 flow가 error로 집계되지 않았는지 확인한다.
2. user activation 전에 비동기 작업이 추가됐는지 확인한다.
3. native input fallback이 Chromium/Firefox/WebKit에서 동작하는지 확인한다.
4. count, per-file, total bytes, MIME/extension/signature policy version을 확인한다.
4. 개수, 파일당 bytes, 전체 bytes, MIME/extension/signature policy version을 확인한다.
raw policy가 port caller에서 들어오지 않고 composition registry의 정확한
`FilePolicyReference` identity로 resolve되는지, verification receipt가 같은
profile/file snapshot에 binding됐는지 확인한다. 같은
@@ -151,19 +151,19 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
조합됐는지 확인한다. 현재 byte/signature 검사만으로 decode safety를
주장하지 않는다.
9. upload를 별도 설치했다면 backend 401/403/409/413/415/422/429/5xx,
CORS/preflight, session TTL/clock skew, part checksum, idempotency, orphan
cleanup과 quarantine queue를 그 feature runbook에서 확인한다.
CORS/preflight, session TTL/clock skew, part별 checksum, 멱등성(idempotency),
고아(orphan) 정리와 quarantine queue를 그 feature runbook에서 확인한다.
### 안전한 조치
- enhanced open/save picker off → native input/direct authorized download
- active-content preview off
- preview pixel/decode/frame probe가 없거나 실패하면 object URL preview off
- client-generated large download off → server-side artifact generation
- broken stream adapter off → bounded fallback 또는 operation 중지; raw exception을
- 확장(enhanced) open/save picker 끄기 → 기본(native) input 또는 권한이 확인된 직접 download
- active-content preview 끄기
- preview pixel/decode/frame probe가 없거나 실패하면 object URL preview 끄기
- client가 만드는 큰 download 끄기 → server에서 산출물 생성
- 고장 난 stream adapter 끄기 → 상한 있는 fallback 또는 operation 중지. raw exception을
성공/EOF로 변환하지 않음
- upload를 별도 설치했다면 multipart concurrency/part size 하향,
resumable off → approved hard cap의 simple upload, 문제 MIME 임시 차단
resumable 끄기 → 승인된 hard cap의 simple upload, 문제 MIME 임시 차단
- expired upload session은 authorization 후 새 session; 기존 session을
재활성화하지 않음
@@ -204,7 +204,7 @@ read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 e
token이나 physical DB name에 넣지 않는다.
3. physical DB name이 세 opaque token에서만 파생됐는지, caller
`databaseNameAssertion`이 exact match인지 확인한다.
4. governance store의 immutable scope + full `BrowserStoragePolicy` binding을
4. governance store의 바꿀 수 없는(immutable) scope와 `BrowserStoragePolicy` 전체 binding을
versionchange, post-open, maintenance 모두에서 확인한다. raw token이나 binding
내용을 incident log에 복사하지 않는다.
5. old tab, worker 또는 test/debug context가 connection을 닫지 않는지 확인한다.
@@ -252,7 +252,7 @@ remote tab 강제 종료, database 삭제, 무한 reload는 금지한다.
### 확인 순서
1. DDL schema version과 record codec version을 구분한다.
2. migration ID, last safe keyset checkpoint, revision fence,
2. migration ID, 마지막으로 안전한 keyset checkpoint, revision fence,
`budgetExhausted`, processed/remaining bucket과 old-writer drain proof를
확인한다.
3. caller budget과 구현 absolute budget(500 rows/30,000ms), async operation 사이
@@ -320,7 +320,7 @@ action이다. runtime이 스스로 DB를 지우는 경우는 하나뿐이다(05-
- N-1 rollback/read-only smoke 통과
- dataset budget/sidecar/receipt count 재검증과 bounded lifecycle fixture 통과
## 6. Origin quota, persistence denial, storage eviction
## 6. Origin quota, 영구 저장 거부, 저장소 축출(eviction)
### 신호
@@ -364,7 +364,7 @@ cursor를 지킨다. failed write의 자동 retry는 다음 조건이 모두 맞
한 번 허용한다.
- 첫 write가 실제 quota failure로 원자적 rollback됨
- 같은 idempotency key, revision fence와 payload digest
- idempotency key, revision fence, payload digest가 모두 같음
- 외부 side effect/cross-store publish가 commit되지 않음
- bounded GC가 실제 candidate를 제거했거나 pressure가 내려감
- 현재 revision/generation 재확인과 새 admission token 발급
@@ -433,8 +433,8 @@ VD-15 목표 runtime을 먼저 구현한다.
manifest schema와 digest를 검증하게 한다.
10. logical row가 commit authority인지 확인한다.
11. VD-15 forward migrator를 설치했다면 source/target physical layout와 journal
version, migration checkpoint, copy-on-write generation, publish authority,
rollback window와 N-1 reader 결과를 확인한다.
version, migration checkpoint, copy-on-write 세대, 게시 권한(publish authority),
rollback 가능 기간과 N-1 reader 결과를 확인한다.
### recovery
@@ -505,8 +505,9 @@ VD-15 목표 runtime을 먼저 구현한다.
전이면 manifest·staging receipt·chunk, commit 뒤면 manifest·chunk가 남음).
삭제 전체가 put의 FINISH~commit 사이에 들어가는 경우는 그때도 put이
`CONFLICT`로 실패하고 bytes가 남지 않았다. 막는 테스트:
`tests/unit/opfs-worker-runtime.test.ts` "leaves no partition bytes when an
approved purge meets another tab's put parked before …"(5가지 순서).
`tests/unit/opfs-worker-runtime.test.ts`의
"leaves no partition bytes when an approved purge meets another tab's put parked before …"
(5가지 순서).
- 한계: 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle
bound(05-07)까지 삭제를 붙잡는다. purge의 `signal`을 abort하면 기다림을
멈추고 `ABORTED`를 반환한다. 삭제 뒤에 줄 선 put·delete도 자기 `signal`로
@@ -516,7 +517,7 @@ VD-15 목표 runtime을 먼저 구현한다.
(point-in-time). 그 전에 시작한 put은 삭제가 기다렸다가 함께 지운다.
모든 승인 purge가 이제 이 lock을 기다리므로, 다른 tab에서 오래 걸리는 put이
있으면 purge도 그만큼 늦게 끝난다.
- lock/worker 문제면 OPFS write off → approved capped fallback 또는 online-only
- lock/worker 문제면 OPFS write 끄기 → 승인된 상한의 fallback 또는 online 전용
- scope binding mismatch면 affected scope를 read-only로 격리하고 registry/
composition을 forward fix; 다른 token path로 bytes를 이동하거나 추측 복구 금지
- sensitive maintenance authority provider/consumer가 없거나 replay/expiry
@@ -539,7 +540,7 @@ committed object를 sync handle로 in-place repair하지 않는다. 새 generati
- sensitive maintenance의 fresh proof consume 성공, replay/expired/mismatched
proof와 provider/consumer 누락은 모두 deletion 전 fail-closed
## 8. Cache Storage/Service Worker stale or poisoned release
## 8. Cache Storage/Service Worker의 낡거나 오염된(poisoned) release
public static Cache release runtime은 존재하지만 cursor/count/deadline이 있는
bounded inspect/cleanup은 아직 없다. Service Worker의 waiting/client-drain
@@ -551,11 +552,11 @@ worker 절차를 적용한다.
### 신호
- incomplete candidate activation
- integrity/type/size mismatch
- auth/private/no-store/opaque policy rejection
- 불완전한 candidate activation
- integrity/type/size 불일치
- auth/private/no-store/opaque 정책 거절
- Service Worker를 별도 선택한 조합의 stale worker/update/reload loop
- active asset miss 또는 offline boot failure
- 활성 asset을 찾지 못함(miss) 또는 offline boot 실패
### 확인 순서
@@ -585,8 +586,8 @@ worker 절차를 적용한다.
static Cache-only 조합:
- 신규 candidate activation/cache write 중지
- verified current 또는 previous release로 explicit rollback
- incomplete candidate와 runtime-public cache부터 owned-prefix cleanup
- 검증된 현재 release 또는 이전 release로 명시적 rollback
- 불완전한 candidate와 runtime-public cache부터 owned-prefix 정리
- 현재 cleanup/inspect가 cache 개수에 대해 unbounded임을 고려해 incident
invocation을 추가 budget으로 반복 실행하지 않는다. VD-15 bounded cursor
runtime 구현 전에는 큰 namespace를 자동 sweep하지 않는다.
@@ -685,15 +686,15 @@ contract/provider/browser/operations component gate에서 `PromotionEvidence`를
| drill | 필수 증적 |
| --- | --- |
| 별도 upload workflow를 설치한 경우 session abort/expiry/checksum | orphan cleanup, quarantine state, retry/idempotency |
| large save abort/integrity | partial commit 0, memory high-water |
| large save abort/integrity | 일부만 된 commit 0건, memory 최고 사용량(high-water) |
| IndexedDB two-tab upgrade blocked | close/retry UX, connection leak 0 |
| IndexedDB governance/lifecycle | opaque scope binding, logical budget/TTL, proof discard, receipt cap |
| interrupted historical migration | old-writer drain proof, 500 rows/30s budget, checkpoint resume, atomicity, N-1 fallback |
| IndexedDB governance/lifecycle | opaque scope binding, 논리 budget/TTL, proof 폐기, receipt 상한 |
| 중단된 과거 migration | old-writer drain proof, 500 rows/30s budget, checkpoint에서 재개, 원자성, N-1 fallback |
| quota/persistence denied/storage clear | reconstructable GC, user data 보존, degraded UI |
| VD-15 coordinator를 설치한 경우 pressure/one-retry | hysteresis, bounded cursor/deadline, store priority와 retry 최대 1회 |
| OPFS journal phase crash/scope mismatch/maintenance authority | bidirectional binding, actual opaque layout, invisible partial object, reconcile summary, integrity, provider/consumer one-time proof |
| OPFS journal phase crash/scope mismatch/maintenance authority | 양방향 binding, 실제 opaque layout, 보이지 않는 partial object, reconcile 요약, 무결성, provider/consumer 일회용 proof |
| OPFS preflight/migration을 설치한 경우 | worker/lock/journal/small operation cleanup, interrupted copy-on-write와 N-1 fallback |
| cache candidate poison/update rollback | expectedContentType binding, active release 불변, previous rollback, caller retain 부재, 2 MiB control cap, auth rejection |
| cache candidate poison/update rollback | expectedContentType binding, 활성 release 불변, 이전 release로 rollback, caller 보관(retain) 없음, 2 MiB control 상한, auth 거절 |
| bounded Cache/SW lifecycle을 설치한 경우 | cursor/count/deadline, waiting activation, controlled-client drain과 network-only rollback |
| preview probe를 설치한 경우 | pixel/decoded-byte/static-only rejection, timeout와 decode resource cleanup |
@@ -729,4 +730,4 @@ promotion 직전에는 다음 repository evidence도 함께 보존한다.
- [VD-11 Browser file and origin-storage 경계](../adr/VD-11-browser-file-and-origin-storage.md)
- [VD-15 Origin storage lifecycle and migration](../adr/VD-15-origin-storage-lifecycle-and-migration.md)
- [VD-14 Resumable download와 background download](../adr/VD-14-resumable-download-and-background-transfer.md)
- [Browser transfer recovery](./browser-transfer-recovery.md)
- [브라우저 전송과 Image CDN 복구](./browser-transfer-recovery.md)
+37 -37
View File
@@ -1,4 +1,4 @@
# Browser transfer and Image CDN recovery
# 브라우저 전송과 Image CDN 복구
이 runbook은 presigned capability, multipart/resumable upload, streaming download와
Image CDN reference runtime을 제품에 조합한 경우에만 적용한다. skeleton의 기본
@@ -20,7 +20,7 @@ browser-managed handoff를 그 기능의 운영 증거로 사용하지 않는다
- part size/count/concurrency와 retry bucket
- download expected/actual byte bucket과 truncated/overrun/integrity outcome
- Image CDN preset/format/width/candidate bucket과 policy rejection
- session age, orphan count, quarantine backlog와 promotion latency
- session 경과 시간, 고아(orphan) 개수, quarantine 적체(backlog)와 승격(promotion) 지연
금지:
@@ -29,8 +29,8 @@ browser-managed handoff를 그 기능의 운영 증거로 사용하지 않는다
- file name, local path, raw ETag, checksum, receipt/token의 실제 값
strict upload checkpoint의 protocol-defined SHA-256 fingerprint/part checksum과
bounded opaque non-authorizing part receipt는 server reconcile을 위한 durable
예외다. account partition/retention 안에서만 보존하고 관측 신호나 ticket에는
크기 상한이 있고 권한을 주지 않는(non-authorizing) opaque part receipt는 server reconcile을
위해 오래 보존하는(durable) 예외다. account partition/retention 안에서만 보존하고 관측 신호나 ticket에는
절대 투영하지 않는다.
- raw backend/body/DOMException message와 stack
@@ -38,19 +38,19 @@ bounded opaque non-authorizing part receipt는 server reconcile을 위한 durabl
| 증상 | 우선 확인 |
| --- | --- |
| capability expiry/403 급증 | BFF/object-store clock, signer credential rotation, expiry ceiling |
| CORS/preflight 실패 | exact origin, method, signed headers, exposed receipt/checksum headers |
| capability expiry/403 급증 | BFF/object-store 시계, signer credential 교체(rotation), expiry 상한 |
| CORS/preflight 실패 | 정확한 origin, method, 서명된 header, 노출한 receipt/checksum header |
| redirect/network failure | proxy/CDN redirect 변경, `redirect:error`, URL origin/path policy |
| 특정 part 반복 실패 | exact offset/length/checksum/idempotency, capability expiry |
| resume conflict | server status와 checkpoint revision/part binding |
| resume 충돌 | server status와 checkpoint revision/part binding |
| status 404/410 반복 | terminal checkpoint 제거와 새 session 생성 여부 |
| complete 뒤 file 불일치 | ordered parts, checksum type, ETag 오해, scan/promotion |
| download truncation/overrun | capability length, content encoding, proxy buffering/transform |
| destination partial save | picker writable abort/close, integrity-before-close |
| image policy rejection 급증 | asset revision, preset registry, dimensions, format/CDN origin |
| stale/broken private image | lazy load 시점과 signed URL minimum lifetime |
| image timeout/decode 실패 급증 | encoded cap, pre-decode metadata, decoded-byte ceiling, probe deadline |
| CDN cache poison 의심 | immutable revision, cache key, `Vary`, source asset registry |
| download 잘림·초과 | capability의 length, content encoding, proxy의 buffering/transform |
| 저장 대상에 일부만 저장됨 | picker writable abort/close, close 전 무결성 확인(integrity-before-close) |
| image 정책 거절 급증 | asset revision, preset registry, 가로·세로 크기, format/CDN origin |
| 낡거나 깨진 private image | lazy load 시점과 signed URL의 최소 수명 |
| image timeout/decode 실패 급증 | encoded 상한, decode 전 metadata, decoded-byte 상한, probe deadline |
| CDN cache 오염(poison) 의심 | 바뀌지 않는 revision, cache key, `Vary`, source asset registry |
## 3. Presigned capability
@@ -116,8 +116,8 @@ runtime이 구현된 제품에만 적용한다.
### 4.3 PUT acknowledgement
1. capability가 expected success status, receipt response header와
`expectedResponseByteLength`를 exact하게 묶는지 확인한다.
1. capability가 기대하는 success status, receipt 응답 header와
`expectedResponseByteLength`를 정확하게 묶는지 확인한다.
2. 실제 `Content-Length`가 expected bytes와 같고 hard response cap 이하인지
확인한다. 204는 expected bytes가 0이어야 하며 header 부재를 0으로 정규화한다.
3. response body EOF까지 동일 deadline 안에서 bounded drain된 뒤 receipt가
@@ -162,9 +162,9 @@ runtime이 구현된 제품에만 적용한다.
이 절차는 `RANGE_RESUMABLE_DOWNLOAD_V1` port/runtime, seekable destination 또는
owned OPFS staging과 provider contract가 구현·조합된 경우에만 적용한다.
1. checkpoint의 protocol, opaque account partition, representation binding,
total bytes, next offset, destination binding, revision과 retention을
검증한다. raw URL, signed header, validator, file path는 checkpoint나
1. checkpoint에 담긴 protocol, opaque account partition, 표현(representation)
binding, 전체 bytes, 다음 offset, 저장 대상(destination) binding, revision과
보존 기간(retention)을 검증한다. raw URL, signed header, validator, file path는 checkpoint나
incident ticket에 없어야 한다.
2. destination의 실제 durable length가 checkpoint offset과 다르면 append하지
않는다. 더 긴 uncommitted tail은 정책과 destination capability가 허용할 때만
@@ -202,8 +202,8 @@ owned OPFS staging과 provider contract가 구현·조합된 경우에만 적용
10. final whole-object SHA-256과 destination close/commit 뒤에만
`SAVED_VERIFIED`로 기록한다.
malformed `Content-Range`, encoded representation drift, validator mismatch,
seek/truncate 실패 또는 crash 뒤 ambiguous tail에서는 신규 Range traffic을
형식이 잘못된 `Content-Range`, encoded representation 변화(drift), validator 불일치,
seek/truncate 실패 또는 crash 뒤 애매한(ambiguous) tail에서는 신규 Range traffic을
중지하고 whole-object restart, browser-managed handoff 또는 명시적 unsupported로
degrade한다.
@@ -266,19 +266,19 @@ degrade한다.
## 7. Kill switch
- direct object-storage transfer off → same-origin BFF proxy 또는 기능 중지
- concurrent multipart → sequential part
- resumable off → 승인된 small-file simple upload 또는 upload 중지
- complete off → active session 유지/reconcile only
- upload pause/resume off → 신규 part 중지, explicit reconcile only
- streaming save off → authorized browser handoff
- Range resume off → whole-object restart 또는 authorized browser handoff
- app-managed background download off → browser-managed handoff 또는 foreground only
- app-managed background upload off → foreground checkpoint resume 또는 upload 중지
- Image descriptor refresh off → fresh descriptor expiry까지만 사용 후 placeholder
- private Image CDN off → authenticated same-origin placeholder
- advanced formats off → approved JPEG/PNG preset
- responsive candidates off → 한 개의 bounded fallback rendition
- object-storage 직접 전송 끄기 → same-origin BFF proxy 또는 기능 중지
- 동시 multipart → 순차 part
- resumable 끄기 → 승인된 small-file simple upload 또는 upload 중지
- complete 끄기 → 활성 session 유지와 reconcile만
- upload pause/resume 끄기 → 신규 part 중지, 명시적 reconcile만
- streaming 저장 끄기 → 권한이 확인된 browser handoff
- Range resume 끄기 → 객체 전체 재시작(whole-object restart) 또는 권한이 확인된 browser handoff
- 앱이 관리하는(app-managed) background download 끄기 → 브라우저가 관리하는(browser-managed) handoff 또는 foreground 전용
- app-managed background upload 끄기 → foreground checkpoint에서 resume 또는 upload 중지
- Image descriptor 갱신(refresh) 끄기 → 받아 둔 fresh descriptor를 expiry까지만 쓰고 그 뒤 placeholder
- private Image CDN 끄기 → 인증된 same-origin placeholder
- 고급 format 끄기 → 승인된 JPEG/PNG preset
- 반응형 후보(responsive candidates) 끄기 → 상한 있는 fallback rendition 한 개
kill switch는 hard byte/pixel/security ceiling을 늘리지 않는다.
@@ -294,7 +294,7 @@ kill switch는 hard byte/pixel/security ceiling을 늘리지 않는다.
- image preset/revision/cache/CSP matrix 통과
- Image descriptor provider를 설치한 경우 expiry/refresh/logout generation
fence와 safe projection 통과
- image pre-decode static metadata, private no-store와 timeout cleanup fault 통과
- image decode 전 정적 metadata, private no-store와 timeout 정리 fault 통과
- Chromium/Firefox/WebKit 동일 case set, zero failure/skipped
- raw URL/query/signed header/bearer token/capability가 log, telemetry,
checkpoint에 없음을 확인
@@ -304,12 +304,12 @@ kill switch는 hard byte/pixel/security ceiling을 늘리지 않는다.
## 9. 제거
1. 신규 capability/session/descriptor 발급 중지
2. active upload complete 또는 explicit abort와 orphan cleanup
2. 진행 중인 upload를 complete하거나 명시적으로 abort하고 orphan 정리
3. non-secret checkpoint를 scope에 맞게 purge
4. private capability revoke와 CDN grace window drain
4. private capability 회수(revoke)와 CDN 유예 기간(grace window) 경과 대기
5. feature transfer/image facade와 composition 제거
6. browser-transfer source와 전용 tests/catalog wiring 제거
7. runtime removal gate, production module inventory, 전체 test/build 재검증
7. runtime 제거 gate, production module 목록(inventory), 전체 test/build 재검증
## 10. 관련 문서
+186 -209
View File
@@ -1,14 +1,13 @@
# CI quality-gate orchestration
# CI 품질 게이트 구성
`config/ci/gates.json` is the executable registry for every gate and the sole
workflow model. `.gitea/workflows/quality-gates.yml` is generated from that
strict v2 contract; it is not an independent configuration authority. Update
the registry, run `corepack pnpm generate:ci-workflow`, and commit the generated
bytes together. `corepack pnpm check:ci-workflow` rejects missing, stale, CRLF,
or otherwise byte-different output. `corepack pnpm check:ci` runs artifact-schema
checking, the typed contract checker, and this workflow drift check. The Gitea
adapter runs each gate as an independent matrix check with full fan-out and no
soft-fail wiring.
`config/ci/gates.json`은 모든 게이트를 담은 실행 가능한 registry이고, workflow 모델은
이것 하나뿐이다. `.gitea/workflows/quality-gates.yml`은 이 엄격한 v2 계약에서 생성한다.
따로 설정을 정하는 정본이 아니다. registry를 고치고
`corepack pnpm generate:ci-workflow`를 돌린 뒤, 생성된 바이트를 함께 커밋한다.
`corepack pnpm check:ci-workflow`는 빠졌거나, 낡았거나, CRLF이거나, 그 밖에 바이트가 다른
출력을 거절한다. `corepack pnpm check:ci`는 산출물 schema 검사, 타입이 있는 계약 검사기,
이 workflow drift 검사를 돈다. Gitea adapter는 게이트마다 독립된 matrix check로 돌린다.
모두 펼쳐서(full fan-out) 돌리고, 실패를 무시하는(soft-fail) 연결은 없다.
## 기준선 갱신과 새 프로젝트 시작 시 초기화할 기준선
@@ -69,38 +68,34 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 실패하는 검사는 없다. 남은 키는 아무것도 끄지 않고, `check:release-admission`(FE-GATE-027)이 `release admission warning: FEATURE_OVERRIDES.<id> … the override does nothing`을, 부팅이 진단 `feature.override.unknown`(warn)을 남긴다(리뷰 09-09) |
| 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` |
Contract loading validates every registered command entry against the
authoritative root package-script graph and lifecycle/install policy before the
runner enters its execution callback. Foreign cwd/workspace script dispatch,
argument-sensitive dispatchers, and ineffective lifecycle suppression therefore
fail preflight even when the later `check:ci` command would never run.
For npm, that root-only boundary also parses options following an explicit
`run`/`run-script` target or implicit `test`/`start`/`stop`/`restart` target:
`--workspace`, `-w`, `--workspaces`, and `--prefix` are foreign manifest scope
and are rejected before execution. The first literal `--` ends npm option
parsing, so later tokens are ordinary script arguments. pnpm and Yarn differ:
their options following the selected script name are forwarded to that script;
their cwd/workspace selectors are rejected only where the manager consumes
them before script selection.
계약을 불러올 때, runner가 실행 callback에 들어가기 전에 등록된 명령 항목을 모두
검증한다. 기준은 정본인 루트 package script 그래프와 lifecycle/install 정책이다. 그래서
다른 cwd/workspace의 script로 넘기는 호출, 인자에 따라 동작이 바뀌는 dispatcher, 효과
없는 lifecycle 억제는 사전 검사(preflight)에서 실패한다. 나중의 `check:ci` 명령이 돌지
않는 경우에도 그렇다. npm에서는 이 루트 전용 경계가 명시적
`run`/`run-script` 대상이나 암묵적 `test`/`start`/`stop`/`restart` 대상 뒤의 옵션도
해석한다. `--workspace`, `-w`, `--workspaces`, `--prefix`는 다른 manifest 범위를
가리키므로 실행 전에 거절한다. 처음 나오는 글자 그대로의 `--`가 npm 옵션 해석을 끝낸다.
그 뒤 token은 일반 script 인자다. pnpm과 Yarn은 다르다. 고른 script 이름 뒤의 옵션은 그
script로 넘어간다. cwd/workspace 선택자는 package manager가 script를 고르기 전에 소비하는
위치에 있을 때만 거절한다.
The npm graph includes existing root-manifest `pre<script>` and `post<script>`
hooks around every explicit `run`/`run-script` dependency and implicit
`start`/`stop`/`restart`/`test` dependency. Hooks are omitted only when ordered
npm options establish an unambiguous effective `--ignore-scripts` value before
the first literal `--`; bare and explicitly true forms omit hooks, while false,
negative, contradictory, malformed, and post-delimiter forms keep traversal or
fail closed. Case-insensitive `npm_config_workspace`, `npm_config_workspaces`,
`npm_config_prefix`, `npm_config_userconfig`, and `npm_config_globalconfig`
assignments are rejected whenever the tokenized command invokes npm. Direct
assignments, static paths whose basename is `env`, exact `command`/`exec`
prefix chains, prior exports, and `set -a` assignments share one prefix grammar.
Only modeled non-scope `env -i`, `env -u`, `env --unset`, and `env --` forms are
allowed; cwd-changing or unknown options fail closed. Dynamic assignment names,
unmodeled environment mutation, npm `--userconfig`/`--globalconfig`, and
unquoted pathname expansion before the npm argument delimiter are rejected.
The gate runner checks the same inherited environment names before loading the
contract or entering the execution callback, so they cannot reach a child gate
process.
npm 그래프는 명시적 `run`/`run-script` 의존과 암묵적
`start`/`stop`/`restart`/`test` 의존마다, 그 앞뒤에 있는 루트 manifest의
`pre<script>`, `post<script>` hook을 포함한다. hook을 빼는 것은 처음 나오는 글자 그대로의
`--` 앞에서, 순서대로 놓인 npm 옵션이 실제로 적용될 `--ignore-scripts` 값을 모호함 없이
정할 때뿐이다. 값 없는 형태와 명시적으로 참인 형태는 hook을 뺀다. 거짓, 부정, 모순, 잘못된
형태, 구분자 뒤의 형태는 hook을 계속 따라가거나 닫힌 쪽으로 실패한다(fail closed).
token으로 나눈 명령이 npm을 부르면 대소문자와 상관없이 `npm_config_workspace`,
`npm_config_workspaces`, `npm_config_prefix`, `npm_config_userconfig`,
`npm_config_globalconfig` 대입을 거절한다. 직접 대입, basename이 `env`인 정적 경로,
정확한 `command`/`exec` 접두 사슬, 앞선 export, `set -a` 대입은 같은 접두 문법 하나를
쓴다. 허용하는 것은 모형으로 정의한, 범위를 바꾸지 않는 `env -i`, `env -u`,
`env --unset`, `env --` 형태뿐이다. cwd를 바꾸거나 모르는 옵션은 닫힌 쪽으로 실패한다.
동적인 대입 이름, 모형에 없는 환경 변경, npm `--userconfig`/`--globalconfig`, npm 인자
구분자 앞의 따옴표 없는 경로 이름 확장은 거절한다. 게이트 runner는 계약을 불러오거나 실행
callback에 들어가기 전에 물려받은 환경 변수에서도 같은 이름을 검사한다. 그래서 그 이름은
자식 게이트 process에 닿지 못한다.
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 12-10에서 줄일 수
있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와
@@ -112,7 +107,7 @@ hook과 npm/yarn 설치는 `--ignore-scripts`가 없으면 그대로 돈다. 둘
`-C`, npm pre/post hook, `npm_config_*`). 이것은 설치 옵션과 관계가 없다. 이유는
파일 머리 주석에도 있다.
The dependency graph is:
의존 그래프는 아래와 같다.
```text
MERGE_READY
@@ -191,8 +186,8 @@ source를 다시 scan했다고 주장하지 않는다.
Provider baseline은 Gitea 1.26.4 이상과 Gitea Runner 1.0.0 이상이다. Linux
runner에는 실행 가능한 `/usr/bin/bwrap`, `/usr/bin/prlimit`,
`/usr/bin/systemd-run`, `/usr/bin/systemctl`, `bwrap --size` 지원, active user
bus, systemd user manager 254 이상, unified cgroup v2와 delegated
`/usr/bin/systemd-run`, `/usr/bin/systemctl`, `bwrap --size` 지원, 활성 user
bus, 254 이상의 systemd user manager, 통합 cgroup v2와 위임된(delegated)
memory/pids/CPU controller가 모두 필요하다. 실행 파일, user manager/version,
trust/archive/path 같은 host-side preflight 실패는 raw report 생성 전에 차단된다.
`bwrap --size` 수용 여부와 실제 delegated controller/limit 값은 owned raw inode를
@@ -214,8 +209,9 @@ sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로
`bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted`로 끝난다.
- `test:system`은 먼저 `scripts/check-system-test-prerequisites.ts`를 돈다. 이
검사는 provider와 같은 namespace 옵션으로 bwrap에서 `/bin/true`를 한 번
띄운다. 실패하면 "this host does not allow unprivileged user and network
namespaces"와 bwrap의 stderr, 위 sysctl 값, 고치는 방법을 적고 exit 1로
띄운다. 실패하면
"this host does not allow unprivileged user and network namespaces"와 bwrap의
stderr, 위 sysctl 값, 고치는 방법을 적고 exit 1로
멈춘다. 전에는 이 검사가 PASS를 낸 뒤 provider 테스트가 bwrap 원문 오류로
실패했다(2026-11-05 desktop에서 114건 중 18건).
- 고치는 방법은 `scripts/check-system-test-prerequisites.ts`가 실패할 때
@@ -236,7 +232,7 @@ verified candidate, `.git` mask, `/tmp`, `/etc`, `/proc`, `/dev`를 read-only로
실패 시, 그리고 성공적으로 sealed evidence를 게시한 뒤에도 supervisor가 소유한
inode만 atomic quarantine을 거쳐 제거하므로 빈 stale report 없이 재시도할 수 있다.
Provider command와 provider-prefixed environment는 bounded length-prefixed bwrap vector로
Provider command와 provider 접두사가 붙은 environment는 크기 상한이 있는 length-prefixed bwrap vector로
`systemd-run` stdin에 전달되어 supervisor/systemd/bwrap wrapper argv나 unit
metadata에 노출되지 않는다. 단, 최종 provider executable의 일반 argv는 같은
UID의 process inspection에 보일 수 있으므로 command 문자열과 인자에 token,
@@ -333,52 +329,47 @@ runtime environment의 `CI_RUNNER_IMAGE`로 전달하며, 값이 비어 있으
gate가 실행 전에 실패한다. Gitea repository variable 이름에는 `CI` prefix를
사용할 수 없으므로 두 이름을 의도적으로 구분한다.
Pull requests and `develop` pushes evaluate merge readiness. Version tags
evaluate merge then release readiness. Production and field evaluation require
an explicit workflow dispatch. The field tier cannot pass until the 28-day
sample threshold decision is recorded. Documentation readiness consumes the
canonical project-note evidence in which both scoped diagrams already received
100/100 `PASS_SCOPED`; the repo ledger preserves the evidence scope and
canonical digests.
pull request와 `develop` push는 merge 준비 상태(merge readiness)를 평가한다. version
tag는 merge를 평가한 뒤 release 준비 상태를 평가한다. production과 field 평가는 명시적인
workflow dispatch가 있어야 한다. field tier는 28일 표본 기준(threshold) 결정이 기록될
때까지 통과할 수 없다. 문서 준비 상태(documentation readiness)는 범위를 정한 두
diagram이 이미 100/100 `PASS_SCOPED`를 받은 정본 project-note 증거를 쓴다. repo
ledger는 그 증거의 범위와 정본 digest를 보존한다.
All jobs upload the shared `artifacts/` tree even after failure. Numeric
retention remains an organization/provider decision; the workflow intentionally
does not invent `retention-days`. The relative minimums are recorded in the
registry: merge evidence through the PR decision, coherent release evidence
through the next release promotion, drill evidence through the next production
promotion, and field evidence through aggregation.
모든 job은 실패한 뒤에도 공유 `artifacts/` 트리를 올린다. 보관 기간 숫자는 조직이나
provider가 정할 일로 남긴다. workflow는 일부러 `retention-days`를 지어내지 않는다.
상대적인 최소 보관 기간은 registry에 기록한다. merge 증거는 PR 결정까지, 서로 맞는
release 증거는 다음 release 승격까지, drill 증거는 다음 production 승격까지, field
증거는 집계까지 보관한다.
Runbook jobs write to the stable path
`artifacts/runbooks/<runbook-id>/record.json`; the dynamic release identity is
stored inside the record.
runbook job은 고정 경로 `artifacts/runbooks/<runbook-id>/record.json`에 쓴다. 바뀌는
release identity는 record 안에 저장한다.
A runbook drill (`drill:runbook`, FE-GATE-021..025) records each verdict as
`PASS`, `FAIL` or `UNVERIFIED` (`scripts/drill-runbook.ts`, record schema in
`scripts/contracts/release-artifacts.ts`). `PASS`/`FAIL` means the drill checked
it against a built `dist/`; it reads no `public/` placeholder, so a missing build
fails. In CI the production stage does not rebuild: `production_gate` downloads
the `promoted-release` artifact of the promotion job, extracts its
`release-candidate.tar.gz` to `.release/promoted-release` after checking it
against the `archive_sha256` of `immutable_build`
(`scripts/verify-ci-candidate-archive.ts`), and each drill command passes
`--release-root .release/promoted-release` (`config/ci/gates.json`). The CI
contract rejects a production gate command that builds or omits the release root
(`scripts/contracts/ci-gates.ts`, 13-03, 1101/13-01). Run locally without
`--release-root`, a drill checks the local build.
runbook drill(`drill:runbook`, FE-GATE-021..025)은 판정마다 `PASS`, `FAIL`,
`UNVERIFIED` 중 하나로 기록한다(`scripts/drill-runbook.ts`, record schema는
`scripts/contracts/release-artifacts.ts`). `PASS`/`FAIL`은 drill이 빌드된 `dist/`를
대상으로 확인했다는 뜻이다. drill은 `public/`의 placeholder를 읽지 않으므로 빌드가 없으면
실패한다. CI의 production 단계는 다시 빌드하지 않는다. `production_gate`는 promotion
job의 `promoted-release` 산출물을 내려받는다. 그 `release-candidate.tar.gz`를
`immutable_build`의 `archive_sha256`과 대조한 뒤
(`scripts/verify-ci-candidate-archive.ts`) `.release/promoted-release`에 푼다. drill
명령마다 `--release-root .release/promoted-release`를 넘긴다(`config/ci/gates.json`).
CI 계약은 빌드하거나 release root를 빠뜨린 production 게이트 명령을 거절한다
(`scripts/contracts/ci-gates.ts`, 13-03, 1101/13-01). 로컬에서 `--release-root` 없이
돌리면 drill은 로컬 빌드를 검사한다.
The hosting gate FE-GATE-019 also reads `.release/promoted-release`: it checks
that archive's `dist` and requires the live host to serve a
`release-manifest.json` with the candidate's `buildId` and `releaseId`, so a
host still serving an earlier release fails (1101/13-01). Because a rebuild in
the same run shares those names, the served `config.json` must also equal the
candidate's outside the two emergency switches and the served `index.html` must
name the candidate's entry script (1103/13-01). The workflow deploys
nothing itself. Between `promotion` and `production_gate` sits the `deployment`
job, the project's deployment slot. It is empty by default: it reports
`deployed=false`, FE-GATE-019 does not probe the host and ends `UNVERIFIED`
(exit 3), and the production stage stays open. To fill it, set `deployment`
in the product-owned `config/ci/product-gates.json` and run `corepack pnpm
generate:ci-workflow` (1103/12-07):
hosting 게이트 FE-GATE-019도 `.release/promoted-release`를 읽는다. 그 archive의 `dist`를
검사하고, live 호스트가 후보(candidate)의 `buildId`와 `releaseId`를 담은
`release-manifest.json`을 내주기를 요구한다. 그래서 아직 이전 release를 내주는 호스트는
실패한다(1101/13-01). 같은 run에서 다시 빌드한 것도 같은 이름을 갖는다. 그래서 호스트가
내준 `config.json`도 두 긴급 스위치를 빼고 후보의 것과 같아야 하고, 호스트가 내준
`index.html`도 후보의 진입 스크립트를 가리켜야 한다(1103/13-01). workflow는 스스로
아무것도 배포하지 않는다. `promotion`과 `production_gate` 사이에 `deployment` job이
있다. 이 job이 프로젝트의 배포 슬롯이다. 기본값은 비어 있다. 그러면 job은
`deployed=false`를 보고하고, FE-GATE-019는 호스트를 probe하지 않고 `UNVERIFIED`(exit
3)로 끝나며, production 단계는 닫히지 않는다. 슬롯을 채우려면 제품이 소유한
`config/ci/product-gates.json`에 `deployment`를 넣고
`corepack pnpm generate:ci-workflow`를 돌린다(1103/12-07). 예는 아래와 같다.
```json
{
@@ -394,56 +385,49 @@ generate:ci-workflow` (1103/12-07):
}
```
The template renders the rest of the slot: it downloads the `promoted-release`
transfer, extracts it to `.release/promoted-release` against the candidate
digest, then runs the script, which deploys `.release/promoted-release/dist`.
`environment` takes only `vars.*` and `secrets.*` values. The template ships
this file empty and never changes it, so a template sync does not meet it;
`config/ci/gates.json` stays the template's, and its contract baseline counts
the template contract only. A slot filled in both files is refused.
슬롯의 나머지는 템플릿이 생성한다. `promoted-release` 전송물을 내려받고, 후보 digest와
대조해 `.release/promoted-release`에 푼 다음, script를 돌린다. 그 script가
`.release/promoted-release/dist`를 배포한다. `environment`는 `vars.*`와 `secrets.*`
값만 받는다. 템플릿은 이 파일을 비운 채로 내보내고 절대 바꾸지 않는다. 그래서 템플릿
동기화가 이 파일과 부딪히지 않는다. `config/ci/gates.json`은 템플릿의 것으로 남고, 그
계약 기준선은 템플릿 계약만 센다. 두 파일 모두에 슬롯을 채우면 거절한다.
`mergeGates` adds the product's own checks, such as a contract check against
the paired backend: `{ "id": "PRODUCT-GATE-001", "name": "backend-contract",
"script": "check:backend-contract" }`. Ids are `PRODUCT-GATE-NNN`; the
`FE-GATE-NNN` ids, their commands, artifacts and readiness formula stay the
template's. Each runs as `corepack pnpm <script>` in the `product_merge_gate`
job, on the same condition as `merge_gate`, without browsers and without the
gate log and evidence artifacts of `ci:gate`. `release_gate` waits for that job
as it waits for `merge_gate`, so a failing product gate also stops the release
build, promotion and deployment of the same run (1105/13-02); with no product
gates the workflow is the template's own. A required check of the branch is
what blocks a pull request merge, so make the job one where it has to. `check:ci`
refuses a script that `package.json` does not define, and a workflow whose
`release_gate` does not wait for the product job, and counts these scripts as
gated.
`mergeGates`는 제품 자체 검사를 더한다. 예를 들어 짝 백엔드와의 계약 검사는
`{ "id": "PRODUCT-GATE-001", "name": "backend-contract", "script": "check:backend-contract" }`이다.
ID는 `PRODUCT-GATE-NNN`이다. `FE-GATE-NNN` ID와 그 명령, 산출물, 준비 상태 공식은
템플릿의 것으로 남는다. 각 검사는 `product_merge_gate` job에서 `corepack pnpm <script>`로
돈다. 조건은 `merge_gate`와 같다. 브라우저 없이, `ci:gate`의 게이트 log와 evidence
산출물 없이 돈다. `release_gate`는 `merge_gate`를 기다리듯 그 job도 기다린다. 그래서
제품 게이트가 실패하면 같은 run의 release 빌드, 승격, 배포도 멈춘다(1105/13-02). 제품
게이트가 없으면 workflow는 템플릿의 것 그대로다. pull request merge를 막는 것은 branch의
required check다. 그러니 merge를 막아야 하는 곳에서는 이 job을 required check로 만든다.
`check:ci`는 `package.json`에 없는 script와, `release_gate`가 제품 job을 기다리지 않는
workflow를 거절한다. 그리고 이 script들을 게이트가 돌리는 것으로 센다.
The slot as stored in `config/ci/gates.json` still follows the same contract
rules. The contract allows the steps `checkout`, `setup-node`,
`frozen-install`, `download` (the `promoted-release` transfer), `extract`, and
one final `deploy` step whose `script` names a package script. Its variables
may only be the `CANDIDATE_ARCHIVE_SHA256` digest of `immutable_build` and
`vars.*` or `secrets.*` values. A slot with a deploy script must download only
the `promoted-release` transfer, extract its `release-candidate.tar.gz` and
bind the digest, so the script deploys the promoted candidate rather than a
rebuild (1103/13-01). `secrets.*` values are rendered on the `deploy` step
alone, not on the job, so checkout, setup-node and the download action never
see them (1103/13-05). The `deploy` step writes `deployed=true` only
after the script succeeds. The job owns no gate, so filling it changes neither
gate ownership nor the contract baseline. Browser boot, live API traffic, smoke after a provider
switch, and anything the runbook marks as needing provider verification are
`UNVERIFIED`. One `FAIL` makes the drill `FAIL` (exit 1). Otherwise any
`UNVERIFIED` makes it `UNVERIFIED` (exit 3), and the gate is not `PASS`. So
without provider evidence the production stage stays open. That is the intended
result: a local drill cannot show that the promoted release can be rolled back.
FE-GATE-016 (`rollback-drill`) is retired because it ran the same FE-RB-005
drill as FE-GATE-025 (`RETIRED_GATE_IDS` in `scripts/contracts/ci-gates.ts`). This keeps gate evidence lookup independent from
slashes or other provider-specific characters in `RELEASE_ID`, while each
workflow artifact remains scoped to its own run.
`config/ci/gates.json`에 저장한 슬롯도 같은 계약 규칙을 따른다. 계약이 허용하는 step은
`checkout`, `setup-node`, `frozen-install`, `download`(`promoted-release` 전송물),
`extract`, 그리고 `script`가 package script를 가리키는 마지막 `deploy` step 하나다.
변수는 `immutable_build`의 `CANDIDATE_ARCHIVE_SHA256` digest와 `vars.*`, `secrets.*`
값만 쓸 수 있다. deploy script가 있는 슬롯은 `promoted-release` 전송물만 내려받고, 그
`release-candidate.tar.gz`를 풀고, digest를 묶어야 한다. 그래서 script는 다시 빌드한
것이 아니라 승격한 후보를 배포한다(1103/13-01). `secrets.*` 값은 job이 아니라
`deploy` step에만 넣는다. 그래서 checkout, setup-node, download action은 그 값을 보지
못한다(1103/13-05). `deploy` step은 script가 성공한 뒤에만 `deployed=true`를 쓴다.
이 job은 게이트를 소유하지 않는다. 그래서 슬롯을 채워도 게이트 소유와 계약 기준선은
바뀌지 않는다. 브라우저 boot, live API 트래픽, provider 전환 뒤의 smoke, runbook이
provider 확인이 필요하다고 표시한 것은 모두 `UNVERIFIED`다. `FAIL`이 하나라도 있으면
drill은 `FAIL`(exit 1)이다. 그렇지 않고 `UNVERIFIED`가 하나라도 있으면
`UNVERIFIED`(exit 3)이고, 게이트는 `PASS`가 아니다. 그래서 provider 증거가 없으면
production 단계는 닫히지 않는다. 의도한 결과다. 로컬 drill은 승격한 release를 rollback할
수 있다는 것을 보여 줄 수 없다. FE-GATE-016(`rollback-drill`)은 FE-GATE-025와 같은
FE-RB-005 drill을 돌렸으므로 폐기했다(`scripts/contracts/ci-gates.ts`의
`RETIRED_GATE_IDS`). 이렇게 하면 게이트 증거를 찾는 일이 `RELEASE_ID`의 slash나 그 밖의
provider별 문자에 영향을 받지 않는다. 그러면서도 workflow 산출물은 각자 자기 run 범위에
남는다.
Browser-backed merge gates install and execute the pinned Chromium, Firefox,
and WebKit engines. This makes route behavior, reflow, native dialog semantics,
theme persistence, and automated accessibility a cross-engine contract rather
than a Chromium-only smoke check.
브라우저를 쓰는 merge 게이트는 버전을 고정한 Chromium, Firefox, WebKit 엔진을 설치해
실행한다. 그래서 route 동작, reflow, 기본 dialog 동작, theme 유지, 자동 접근성 검사는
Chromium에서만 보는 smoke check가 아니라 엔진 전체에 걸친 계약이 된다.
`FE-GATE-005`의 unit suite에는 client cache/storage의 deterministic contract가
포함된다. `storage-registry.test.ts`는 key별 codec, schema/TTL, 16,384-byte
@@ -460,9 +444,9 @@ local namespace로만 resolve하고 query key/data를 wire에 보내지 않으
bootstrap에 존재하고 browser capability getter가 실패해도 boot가
`DEGRADED_LOCAL_ONLY`로 계속되는지 확인한다.
`FE-GATE-008`의 `test:browser-capabilities` suite는 File/Blob, native file
input, IndexedDB, OPFS, Cache Storage와 StorageManager reference runtime을 Vite
dev origin의 실제 browser API에 연결한다. API가 없는 engine에서는 skip하지 않고
`FE-GATE-008`의 `test:browser-capabilities` suite는 File/Blob, 브라우저 기본 file
input, IndexedDB, OPFS, Cache Storage와 StorageManager의 reference runtime을
Vite dev origin의 실제 browser API에 연결한다. API가 없는 engine에서는 skip하지 않고
adapter의 명시적인 `UNSUPPORTED` fallback을 검증한다. 생성한 database, OPFS
namespace와 owned cache는 각 test가 자신이 만든 opaque namespace만 정리한다.
@@ -480,7 +464,7 @@ blocking으로 검증한다.
임시 repository에서도 base typecheck, architecture, test, build가 통과하는지
검증해 skeleton의 선택성을 유지한다. browser file/storage와 realtime runtime은
각각 독립 removal fixture와 JUnit evidence를 가지며, realtime fixture는 공통
event authority, SSE, WebSocket, bounded Polling, Web Push source와 공개 export,
event authority, SSE, WebSocket, 상한 있는(bounded) Polling, Web Push의 source와 공개 export,
전용 boundary script를 제거한 뒤 base gate를 다시 실행한다.
같은 `FE-GATE-010`의 `FE-REG-QUERY` governance는 installed query마다
@@ -492,84 +476,78 @@ reference runtime은 계속 미조립이다.
현재 `FE-GATE-008` browser-capability suite에는 실제 두 page의
BroadcastChannel/localStorage fallback scenario가 아직 없다. unit fake 통과를
native multi-tab promotion evidence로 간주하지 않는다. 이 gap은
[Client cache and browser storage platform](../design/2026-07-28-client-cache-and-storage-design.md)의
[클라이언트 캐시·브라우저 저장소 플랫폼 설계](../design/2026-07-28-client-cache-and-storage-design.md)의
완료 기준에 미완료로 남아 있다. 현재 장애 분류와 안전한 local-only 복구 절차는
[Client cache and Web Storage recovery](./client-cache-and-storage-recovery.md)를
[클라이언트 캐시와 Web Storage 복구](./client-cache-and-storage-recovery.md)를
따른다.
Repository variables required by higher tiers:
상위 tier가 요구하는 repository 변수는 아래와 같다.
- `RUNNER_IMAGE_DIGEST` for the immutable job-container image digest used by the
`ubuntu-latest` runner label; the workflow exposes it to gates as
`CI_RUNNER_IMAGE` (required by every tier)
- `HOSTING_BASE_URL` for live header verification of the deployed promoted
release (FE-GATE-019, production stage). Without it the gate fails; the
local fixture result is `UNVERIFIED`. It is probed only when the
`deployment` job deployed the release
- `APP_PROFILE` for the runtime profile the release candidate is built from
(`local`, `development`, `staging`, `production`;
`scripts/generate-runtime-config.ts`). An unset value builds `local`; an empty
value fails the build.
- `RELEASE_TARGET` for the environment FE-GATE-027 admits the candidate to
(`scripts/check-release-admission.ts`). It has no default. The immutable_build
job runs FE-GATE-015 and then FE-GATE-027, and FE-GATE-027 refuses the
candidate when `APP_PROFILE` is set and differs from `RELEASE_TARGET`. Both are
repository-wide variables, so set them together for each release.
FE-GATE-027 runs `scan:dependency-advisories` first and the admission after
it (1103/13-03, 1106/13-01). It applies
`config/security/vulnerability-policy.json` and its exceptions to the
registry's advisory report for the lockfile (pnpm's audit command with
`--json`) and writes the result to the gate log
and `artifacts/security/dependency-advisories.json`: `PASS`,
`POLICY_VIOLATION` (what the production promotion would refuse, with the
findings) or `UNVERIFIED` (no registry). It never fails the gate, because an
advisory database that changes under unchanged code would break releases;
the signed verdict of the vulnerability provider still decides promotion.
The job console shows only one PASS/FAIL line per gate, so the
immutable_build job uploads both gates' logs and evidence and this record as
the run artifact `immutable-gate-evidence-<run>-<attempt>`, whether the job
passed or failed (1105/13-01). It holds the files the run produced. `ci:gate`
stops at the first command that fails, and the scan runs before the
admission, so a run whose admission was refused still has the advisory
record. When FE-GATE-015 fails, FE-GATE-027 does not run, and the run has
neither its log nor the record. Read why FE-GATE-015 or FE-GATE-027 failed,
and the advisory status, there.
`renovate.json` opens security update PRs once a Renovate runner is attached;
a dependency update re-approves the dependency baseline in the same change
- `RUNNER_IMAGE_DIGEST`: `ubuntu-latest` runner label이 쓰는, 바꿀 수 없는 job container
image의 digest. workflow는 이 값을 게이트에 `CI_RUNNER_IMAGE`로 넘긴다(모든 tier가
요구한다)
- `HOSTING_BASE_URL`: 배포된 승격 release의 live 헤더 검증용(FE-GATE-019, production
단계). 없으면 게이트는 실패한다. 로컬 fixture 결과는 `UNVERIFIED`다.
`deployment` job이 release를 배포했을 때만 probe한다
- `APP_PROFILE`: release 후보를 빌드할 runtime profile(`local`, `development`,
`staging`, `production`;
`scripts/generate-runtime-config.ts`). 설정하지 않으면 `local`로 빌드한다. 빈 값이면
빌드가 실패한다.
- `RELEASE_TARGET`: FE-GATE-027이 후보를 승인해 들여보낼 환경
(`scripts/check-release-admission.ts`). 기본값이 없다. immutable_build job은
FE-GATE-015를 돌린 뒤 FE-GATE-027을 돌린다. FE-GATE-027은 `APP_PROFILE`이 설정돼 있고
`RELEASE_TARGET`과 다르면 후보를 거절한다. 둘 다 repository 전체 변수이므로 release마다
함께 설정한다.
FE-GATE-027은 `scan:dependency-advisories`를 먼저 돌리고 승인(admission)을 그 뒤에
돌린다(1103/13-03, 1106/13-01). 이 scan은 lockfile에 대한 registry의 advisory
report(pnpm의 audit 명령에 `--json`)에
`config/security/vulnerability-policy.json`과 그 예외를 적용한다. 결과는 게이트 log와
`artifacts/security/dependency-advisories.json`에 쓴다. 결과는 `PASS`,
`POLICY_VIOLATION`(production 승격이 거절할 내용과 그 발견 사항),
`UNVERIFIED`(registry 없음) 중 하나다. 이 scan은 게이트를 실패시키지 않는다. 코드가
그대로여도 advisory 데이터베이스가 바뀌면 release가 깨지기 때문이다. 승격은 여전히
vulnerability provider의 서명된 판정이 정한다.
job 콘솔은 게이트마다 PASS/FAIL 한 줄만 보여 준다. 그래서 immutable_build job은 job의
성공·실패와 상관없이 두 게이트의 log와 evidence, 이 기록을 run 산출물
`immutable-gate-evidence-<run>-<attempt>`로 올린다(1105/13-01). 이 산출물에는 그
run이 만든 파일이 들어 있다. `ci:gate`는 처음 실패한 명령에서 멈추고, scan은 승인보다
먼저 돈다. 그래서 승인이 거절된 run에도 advisory 기록이 있다. FE-GATE-015가 실패하면
FE-GATE-027은 돌지 않는다. 그래서 그 run에는 FE-GATE-027의 log도 기록도 없다.
FE-GATE-015나 FE-GATE-027이 실패한 이유와 advisory 상태는 이 산출물에서 읽는다.
Renovate runner를 붙이면 `renovate.json`이 보안 업데이트 PR을 연다. 의존성 업데이트는
같은 변경에서 의존성 기준선을 다시 승인한다
(`update:dependency-baseline`).
- `FIELD_WEB_VITALS_INPUT` for the privacy-approved field sample document
- `MIN_ELIGIBLE_SAMPLES` after the baseline decision
- `VULNERABILITY_PROVIDER_COMMAND` and `PROVENANCE_PROVIDER_COMMAND` for the
independently operated scanner and attestor commands
- `FIELD_WEB_VITALS_INPUT`: 개인정보 검토를 통과한 field 표본 문서
- `MIN_ELIGIBLE_SAMPLES`: 기준선 결정 뒤에 설정한다
- `VULNERABILITY_PROVIDER_COMMAND`, `PROVENANCE_PROVIDER_COMMAND`: 따로 운영하는
scanner와 attestor 명령
- `VULNERABILITY_PUBLIC_KEY_PATH`, `VULNERABILITY_KEY_ID`,
`PROVENANCE_PUBLIC_KEY_PATH`, and `PROVENANCE_KEY_ID` for separately managed
trusted Ed25519 verification material
`PROVENANCE_PUBLIC_KEY_PATH`, `PROVENANCE_KEY_ID`: 따로 관리하는 신뢰할 수 있는
Ed25519 검증 자료
Advisories at or above the policy's `high` that `scan:dependency-advisories`
reports for this lockfile, checked 2026-11-04 (review 1103/13-03). Check again
by 2026-12-04 or when the update below is made. The development-only ones
(storybook, vite, vitest, undici, brace-expansion, nanoid, source-map-js) were
updated within their declared ranges and are gone.
`scan:dependency-advisories`가 이 lockfile에 대해 보고한, 정책의 `high` 이상 advisory는
아래와 같다. 2026-11-04에 확인했다(리뷰 1103/13-03). 2026-12-04까지 또는 아래 업데이트를
할 때 다시 확인한다. 개발 전용 의존성(storybook, vite, vitest, undici, brace-expansion,
nanoid, source-map-js)은 선언한 범위 안에서 업데이트해서 없어졌다.
| Advisory | Package | Fixed in | Why it is not updated yet |
| Advisory | 패키지 | 고친 버전 | 아직 업데이트하지 않은 이유 |
|---|---|---|---|
| GHSA-mrhx-c7xc-m3w5 (high) | `zod` 4.4.3 (production) | 4.6.6 | A direct production upgrade needs a `config/security/dependency-change-evidence.json` entry whose reviewer is not its owner. 4.6.7 also adds about 7 KB gzip of initial JavaScript, over the bundle budget, so the update needs a budget decision as well. The app reads HTTP bodies with a byte limit, which narrows the large-collection input the advisory needs (review estimate) |
| GHSA-qwww-vcr4-c8h2 (high) | `react-router` 7.18.1, through `react-router-dom` (production) | 7.18.2 | Same evidence rule. The advisory concerns RSC mode, which this browser-router SPA does not use (review estimate, not verified). 7.18.5 adds about 470 B of initial JavaScript |
| GHSA-mrhx-c7xc-m3w5 (high) | `zod`(production. 지금 버전은 `package.json`) | 4.6.6 | production 직접 의존성을 올리려면 `config/security/dependency-change-evidence.json` 항목이 필요하고, 그 항목의 reviewer는 owner가 아니어야 한다. 4.6.7은 초기 JavaScript를 gzip으로 약 7 KB 늘려 번들 예산을 넘는다. 그래서 업데이트에는 예산 결정도 필요하다. 앱은 HTTP 본문을 바이트 상한을 두고 읽는다. 그래서 이 advisory가 필요로 하는 큰 collection 입력이 좁아진다(리뷰 추정) |
| GHSA-qwww-vcr4-c8h2 (high) | `react-router`, `react-router-dom`을 거쳐 들어옴(production. 지금 버전은 `pnpm-lock.yaml`) | 7.18.2 | 같은 evidence 규칙을 따른다. 이 advisory는 RSC 모드에 관한 것이다. browser router를 쓰는 이 SPA는 RSC 모드를 쓰지 않는다(리뷰 추정, 확인하지 않음). 7.18.5는 초기 JavaScript를 약 470 B 늘린다 |
두 provider role은 서로 다른 key ID뿐 아니라 canonical DER-SPKI public-key bytes도
사용해야 한다. 동일 key를 서로 다른 ID로 재등록한 구성도 finalizer가 거절한다.
If any external provider command, report, trust path, or key ID is absent,
promotion remains unavailable with `FAIL_UNVERIFIED`; there is no local
generator/restore fallback.
외부 provider 명령, report, trust 경로, key ID 중 하나라도 없으면 승격은
`FAIL_UNVERIFIED`로 막힌 채 남는다. 로컬에서 생성하거나 복원하는 대체 경로(fallback)는
없다.
Each provider command must atomically emit strict provider evidence v2 from
the supervisor bindings for evidence type, issued/expires timestamps, run
ID/attempt, `PROVIDER_INVOCATION_NONCE`, source identity, candidate digests,
key ID, and DER-SPKI key fingerprint. Promotion receives the two supervisor
job outputs as `VULNERABILITY_INVOCATION_NONCE` and
`PROVENANCE_INVOCATION_NONCE`; do not replace them with constants or values
parsed from provider reports.
provider 명령은 각각 supervisor가 묶어 준 값으로 엄격한 provider evidence v2를 원자적으로
내보내야 한다. 묶는 값은 evidence 종류, 발급·만료 시각, run ID/attempt,
`PROVIDER_INVOCATION_NONCE`, source identity, 후보 digest, key ID, DER-SPKI key
fingerprint다. 승격은 두 supervisor job의 output을 `VULNERABILITY_INVOCATION_NONCE`와
`PROVENANCE_INVOCATION_NONCE`로 받는다. 이 값을 상수나 provider report에서 읽은 값으로
바꾸지 않는다.
Promotion verification/staging step과 promoted-release upload action 사이에는
어떤 step도 둘 수 없고 upload에는 `if: always()`를 사용할 수 없다. 이 인접성은
@@ -600,7 +578,7 @@ canary tree를 recursive 삭제하지 않는다. stable `.release/promoted-stagi
directory를 만들거나 재사용하지 않는다. exact five는 captured archive 한 개,
captured report 두 개와 process 안에서 생성한 provider/promotion verification v3
두 개이며 promotion
record는 provider record, local assessment, report hashes와 run/source/candidate/
record는 provider 기록, 로컬 평가(local assessment), report hash와 run/source/candidate/
nonces/key identities/trust-policy hash 및 signed `secretScanAttestation`을 함께
bind한다. 이 attestation은 PASS와 local-assessment/source-set/policy/SARIF/
scan-input digest를 포함한다. Supervisor/finalizer는 captured archive에서 기대
@@ -613,7 +591,7 @@ Descriptor-relative 정리는 ancestor/leaf 교체와 symlink를 fail-closed로
upload action의 same-UID pathname reopen 또는 atomic
`renameat2` handoff를 보장하지 않는다. staging Gitea smoke/native adapter 확인
전에는 그 경계를 닫았다고 보고하지 않는다. 실제 smoke는 exact-five
upload-download와 success, validation failure, upload failure, cancellation 각각의
upload-download와, 성공·검증 실패·upload 실패·취소 각각의
cleanup을 관찰해야 한다. 현재 repository에는 native uploader나 `renameat2`
보장이 없다.
또한 portable Node의 `mkdir`와 최초 pathname `lstat`는 atomic하지 않다. 구현은
@@ -628,6 +606,5 @@ private `0700` ancestor와 exclusive single-tenant runner가 필수다.
배제한 trusted runner/native cleanup 또는 격리된 test fixture가 잔여 directory를
후처리해야 한다.
Branch protection must mark each `FE-GATE-* / <name>` check required for its
declared tier. This repository cannot configure server-side protection by
committing a file.
branch 보호 설정은 각 `FE-GATE-* / <name>` check를 선언한 tier에 맞게 required로 표시해야
한다. 이 repo는 파일을 커밋하는 것으로 서버 쪽 보호 설정을 바꿀 수 없다.
@@ -1,19 +1,19 @@
# Client cache and Web Storage recovery
# 클라이언트 캐시와 Web Storage 복구
- 적용 대상: production-composed TanStack memory cache, registered Web Storage,
cross-tab invalidate-only runtime
- 적용 대상: production에 조립된 TanStack memory cache, 등록된 Web Storage,
cross-tab 무효화 전용(invalidate-only) runtime
- 비대상: query persistence와 IndexedDB query cache
- 기준일: 2026-07-28
현재 query persistence는 정책과 runtime에서 `disabled`다. 기존 IndexedDB
reference runtime은 query cache에 조립되지 않았으므로 query-cache incident에서
database 삭제, migration 또는 hydration 조치를 수행하지 않는다.
session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle도
session/account에 묶인 Query lifecycle, 엄격한 query 정책과 Web Storage v2 lifecycle도
현재 `DESIGNED_NOT_IMPLEMENTED`다. 아래 목표 절차를 현재 runtime의 보장으로
해석하지 않는다.
## Public cache staging repair와 offline activation (STO-03 ~ STO-05)
## Public cache staging 복구와 offline 활성화 (STO-03 ~ STO-05)
- release marker는 "staging이 끝났다"는 **주장**이고 모든 entry의 존재·digest
증거가 아니다. 같은 manifest로 `stageRelease`를 다시 호출하면 runtime이
@@ -172,7 +172,7 @@ partition은 아직 없다. 따라서 다음을 과장해 보장하지 않는다
- persisted query data가 account별로 분리된다.
실제 account-switching 제품을 배포하기 전에 session owner 기반 local admission
fence, old QueryClient cancel/clear, late-result generation fence와 account epoch를
fence, 옛 QueryClient의 cancel/clear, 늦게 온 결과(late-result)의 generation fence와 account epoch를
구현해야 한다. 그 전에는 external auth owner와 서버 authorization을
authoritative하게 유지하고, 의심되는 stale personal data incident는 security
owner에게 escalation한다.
@@ -215,8 +215,8 @@ dedupe/high-watermark state와 pending remote set을 idempotent하게 정리한
revalidation 성공
- duplicate/self/stale event가 추가 refetch를 만들지 않음
- sequence gap은 bounded active-query reconciliation으로 종료
- Web Storage corrupt/quota scenario가 exact-key cleanup 또는 documented fallback
으로 종료
- Web Storage 손상·quota 시나리오가 정확한 key 단위 정리(exact-key cleanup) 또는 문서화된
fallback으로 종료
- raw key/value/query/user identifier가 diagnostic evidence에 없음
- affected browser의 manual two-tab smoke 기록 보존
@@ -236,4 +236,4 @@ manual smoke나 transport-only suite를 production promotion evidence의 영구
- [VD-13 Client cache scope and persistence](../adr/VD-13-client-cache-scope-and-persistence.md)
- [TypeScript, 상태 소유권, 데이터 흐름](../design/2026-07-26-typescript-state-and-data-flow-design.md)
- [Backend API degradation](../runbooks/FE-RB-003.md)
- [Release, cache, and rollback contract](./release-cache-rollback.md)
- [Release·캐시·롤백 계약](./release-cache-rollback.md)
+19 -21
View File
@@ -1,16 +1,15 @@
# Performance evidence contract
# 성능 증거 계약
Performance evidence is deliberately split by measurement context:
성능 증거는 측정 환경(context)에 따라 일부러 나눈다.
- `bundle.json` records production build output and enforces initial JavaScript
at 202 KiB gzip, the number of initial JavaScript files (`initialJsFiles`),
and every lazy chunk at 120 KiB gzip. A failure names each exceeded limit,
the measured value and the excess (1103/15-03).
- `lab.json` records Chromium/runner/viewport/network/CPU/cache/build context and
enforces LCP 2.5 s, CLS 0.10, and the named route interaction at 200 ms.
- `field-web-vitals.json` records consent-filtered, route-ID aggregated,
release-specific production samples over 28 days and evaluates p75 LCP, CLS,
and INP against 2.5 s, 0.10, and 200 ms.
- `bundle.json`은 production 빌드 출력을 기록한다. 초기 JavaScript gzip 202 KiB,
초기 JavaScript 파일 수(`initialJsFiles`), lazy chunk마다 gzip 120 KiB 상한을
강제한다. 실패하면 넘은 상한마다 측정값과 초과량을 적는다(1103/15-03).
- `lab.json`은 Chromium/runner/viewport/network/CPU/cache/build 환경을 기록한다.
LCP 2.5 s, CLS 0.10, 지정한 route의 interaction 200 ms를 강제한다.
- `field-web-vitals.json`은 28일 동안의 production 표본을 기록한다. 표본은 동의한
것만 거르고, route ID별로 모으고, release별로 나눈다. p75 LCP, CLS, INP를 각각
2.5 s, 0.10, 200 ms와 비교한다.
## 번들 예산의 기준선과 여유
@@ -153,16 +152,15 @@ LCP 2,386ms, interaction 184.5ms로 통과했다. 한 번씩 판정했다면 int
1,968~2,072ms로 모두 통과했다. 한 번 측정한 판정은 호스트 부하에 따라
뒤집히고, 중앙값 판정은 두 번 모두 통과였다.
The field minimum eligible-sample threshold is intentionally unresolved until
a privacy-approved telemetry baseline exists. Therefore the field command
fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
`FIELD_WEB_VITALS_INPUT` and `MIN_ELIGIBLE_SAMPLES` only after that decision is
recorded. The external input must identify a production release and an exact
28-day export window, name the source/export, carry privacy-approval and
threshold-decision references, and contain only non-negative route-ID samples.
The environment threshold must be a positive integer equal to the approved
decision embedded in the input. Invalid metadata fails as `FAIL_UNVERIFIED`;
the example can never serve as production evidence.
field의 최소 유효 표본 수(eligible-sample threshold)는 개인정보 검토를 통과한
telemetry 기준선이 생길 때까지 일부러 정하지 않는다. 그래서 예시 입력으로 field 명령을
돌리면 `FAIL_UNVERIFIED`로 실패한다(fail closed). `FIELD_WEB_VITALS_INPUT`과
`MIN_ELIGIBLE_SAMPLES`는 그 결정이 기록된 뒤에만 넣는다. 외부 입력은 production
release 하나와 정확한 28일 export 기간을 가리켜야 한다. 또 source/export 이름을 적고,
개인정보 승인과 기준값 결정의 참조를 담고, 음수가 아닌 route ID 표본만 담아야 한다. 환경
변수의 기준값은 양의 정수여야 하고, 입력에 담긴 승인된 결정과 같아야 한다. metadata가
잘못되면 `FAIL_UNVERIFIED`로 실패한다. 예시는 어떤 경우에도 production 증거가 될 수
없다.
## 초기 청크 수와 HTTP/1.1
+128 -142
View File
@@ -1,25 +1,23 @@
# Release, cache, and rollback contract
# Release·캐시·롤백 계약
Each deployment is an immutable `releases/<releaseId>/` artifact set. The
provider adapter must upload assets, release manifest, runtime config, and
verify asset reachability before atomically switching the active HTML pointer.
The post-switch boot, route, API, telemetry, and reload-loop smoke checks close
the deployment.
배포 하나는 바꿀 수 없는 `releases/<releaseId>/` 산출물 묶음이다. provider adapter는
활성 HTML 포인터를 원자적으로 바꾸기 전에 asset, release manifest, runtime config를
올리고 asset에 닿는지 확인해야 한다. 바꾼 뒤 boot, route, API, telemetry, 새로 고침
반복(reload loop) smoke check를 통과해야 배포가 끝난다.
Rollback selects a prior release tuple, confirms its assets and runtime/API
compatibility, atomically switches the complete set, performs the provider
cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
HTML alone, or declaring recovery from cache-purge completion is prohibited.
Recovery is established by old/new reachability probes.
롤백은 이전 release 묶음(tuple)을 고른다. 그 묶음의 asset과 runtime/API 호환성을
확인하고, 묶음 전체를 원자적으로 바꾸고, provider의 캐시 조치를 하고, smoke check를
다시 돈다. 옛 commit을 다시 빌드하는 것, HTML만 바꾸는 것, 캐시 purge가 끝났다는 것만으로
복구를 선언하는 것은 금지다. 복구는 옛 release와 새 release에 닿는지 보는 probe로
확인한다.
Before deploying a promoted release later, or rolling back to one, re-verify
its promoted bundle (the five files uploaded by the `promotion` job) with the
archived mode (review 13-04). Provider evidence expires two hours after issue,
so the normal mode refuses any release promoted before that. The archived mode
still checks signatures, digests and the exact five members, and judges
freshness at the release's recorded promotion time
(`promotion-verification.json` `verifiedAt`, which may not lie in the future).
New promotion never uses it (`scripts/lib/exact-promotion-bundle.ts`).
승격(promotion)한 release를 나중에 배포하거나 그 release로 롤백하기 전에는 승격
묶음(`promotion` job이 올린 파일 다섯 개)을 archived 모드로 다시 검증한다(리뷰 13-04).
provider evidence는 발급 두 시간 뒤 만료된다. 그래서 일반 모드는 그보다 먼저 승격한
release를 모두 거절한다. archived 모드도 서명, digest, 정확한 다섯 member를 검사한다.
다만 신선도는 release에 기록된 승격 시각으로 판단한다
(`promotion-verification.json` `verifiedAt`, 미래 시각이면 안 된다).
새 승격에는 이 모드를 쓰지 않는다(`scripts/lib/exact-promotion-bundle.ts`).
```bash
VULNERABILITY_PUBLIC_KEY_PATH=... VULNERABILITY_KEY_ID=... \
@@ -33,99 +31,89 @@ mkdir <release dir> && tar -xzf <promoted bundle directory>/release-candidate.ta
corepack pnpm drill:runbook -- FE-RB-005 --release-root <release dir>
```
The expected values come from the release record, not from the bundle. The
drill then checks that release's build/config/manifest tuple and its assets,
not the local build. It ends `UNVERIFIED` until the provider switch and smoke
are recorded, because those happen outside this repository.
기대값은 묶음이 아니라 release 기록에서 가져온다. 그다음 drill은 로컬 빌드가 아니라
그 release의 build/config/manifest 묶음과 asset을 검사한다. provider 전환과 smoke는 이
repo 밖에서 일어난다. 그래서 그 결과가 기록될 때까지 drill은 `UNVERIFIED`로 끝난다.
The provider-independent cache defaults are:
provider와 상관없는 캐시 기본값은 아래와 같다.
- hashed assets: `public, max-age=31536000, immutable`
- hashed asset: `public, max-age=31536000, immutable`
- HTML: `no-cache`
- app routes: the router uses browser history, so every path the build has
no file for (a reload, a bookmark, a shared link) is answered with the
release's `index.html` and the HTML headers (SPA fallback). A missing
hashed asset stays a 404; it never falls back to HTML
- runtime config and release manifest: `no-store`
- public source maps: disabled
- service worker/offline cache: disabled, unless the static selection in
`src/features/product-capabilities.ts` is `ACTIVE` or
`REMOVE_REGISTRATION`; then `dist` holds exactly the selected
`service-worker.js`, served `no-cache` so the browser's update check sees
each release's worker
- 앱 경로: router가 browser history를 쓴다. 그래서 빌드에 파일이 없는 모든 경로(새로
고침, 북마크, 공유 링크)에는 그 release의 `index.html`과 HTML 헤더로 답한다(SPA
fallback). 없는 hashed asset은 404로 남고, HTML로 대신 답하지 않는다
- runtime config와 release manifest: `no-store`
- 공개 소스맵: 끔
- Service Worker/offline 캐시: 끔. 단
`src/features/product-capabilities.ts`의 정적 선택이 `ACTIVE`나
`REMOVE_REGISTRATION`이면 `dist`에 선택한 `service-worker.js` 하나만 들어간다. 이
파일은 `no-cache`로 내보내서 브라우저의 업데이트 검사가 release마다 그 worker를 보게
한다
HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
to the declared allowlist; a cache-correct response with a mismatched
`Content-Type` still fails the hosting gate.
HTML, JSON config/manifest, hashed JavaScript의 MIME type도 선언한 허용 목록(allowlist)과
비교한다. 캐시 헤더가 맞아도 `Content-Type`이 다르면 hosting gate는 실패한다.
`corepack pnpm verify:hosting-headers` compares the declared headers with a
deterministic fixture when `HOSTING_BASE_URL` is unset. That only shows the
declarations agree with each other, so its result is `UNVERIFIED` (exit 3), not
`PASS` (review 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). Only
`mode: "live"` can pass. The live target must be its canonical, non-loopback
HTTPS root URL. Each required surface must return HTTP 200 without leaving that
origin before its cache, content-type, and security headers can count as
deployment evidence. The hashed asset it requests is the entry script named by
the served `index.html`, so it checks the release that is actually deployed.
It also requests `appRoute` (`/__probe/deep-link`, a path no build has a file
for): the host must answer 200 with the same `index.html` (the same entry
script) and the HTML headers, so a host without the SPA fallback fails
(review 1101/13-04). When the build ships a worker it requests
`/service-worker.js` and expects `no-cache` and no redirect at all, not even
one inside the origin: browsers fetch the worker script with redirect mode
`error`, so registration, every update check and the `REMOVE_REGISTRATION`
kill switch fail behind one (review 1106/06-01). The surfaces and their
headers are declared in `config/hosting/cache-policy.json`. For each cacheable
extension the release has under `assets/` (`.css`, `.js`, `.woff2` and the rest of
`CACHEABLE_ASSET_CONTENT_TYPES`) it requests the first such file and expects
exactly that type (`hashedAsset.css` and so on). The worker's install refuses
the whole release when one precached asset has another type, while a page
still uses a font served as `application/octet-stream` (review 1103/06-03).
The install fetch also refuses any redirect, so an asset the host answers only
after a redirect fails even when the final answer is a correct 200 (review
1105/06-02). This asset check runs for a build without a worker too: under
`nosniff` a script or style of another type breaks the page anyway, and a later
release that turns the worker on then needs no new hosting check. A font or
image of another type fails it although a worker-free page still loads it.
`HOSTING_BASE_URL`이 없으면 `corepack pnpm verify:hosting-headers`는 선언한 헤더를
결정적(deterministic) fixture와 비교한다. 이것은 선언끼리 서로 맞는다는 것만 보여 준다.
그래서 결과는 `PASS`가 아니라 `UNVERIFIED`(exit 3)다
(리뷰 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). 통과할 수 있는 것은
`mode: "live"`뿐이다. live 대상은 loopback이 아닌 정식(canonical) HTTPS 루트 URL이어야
한다. 필요한 surface마다 그 origin을 벗어나지 않고 HTTP 200을 돌려줘야 한다. 그래야 그
surface의 캐시, content-type, 보안 헤더를 배포 증거로 셀 수 있다. probe가 요청하는
hashed asset은 호스트가 내준 `index.html`이 가리키는 진입 스크립트다. 그래서 실제로
배포된 release를 검사한다. probe는 `appRoute`(`/__probe/deep-link`, 어느 빌드에도 파일이
없는 경로)도 요청한다. 호스트는 200과 함께 같은 `index.html`(같은 진입 스크립트)과 HTML
헤더로 답해야 한다. 그래서 SPA fallback이 없는 호스트는 실패한다(리뷰 1101/13-04).
빌드가 worker를 실으면 probe는 `/service-worker.js`를 요청하고 `no-cache`를 기대한다.
redirect는 origin 안의 것도 하나도 허용하지 않는다. 브라우저는 worker 스크립트를
redirect 모드 `error`로 가져온다. 그래서 redirect가 하나라도 끼면 등록, 모든 업데이트
검사, `REMOVE_REGISTRATION` kill switch가 실패한다(리뷰 1106/06-01). surface와 그
헤더는 `config/hosting/cache-policy.json`에 선언한다. release의 `assets/` 아래에 있는
캐시 가능한 확장자(`.css`, `.js`, `.woff2`와 그 밖의
`CACHEABLE_ASSET_CONTENT_TYPES`)마다 probe는 첫 파일 하나를 요청하고 정확히 그 type을
기대한다(`hashedAsset.css` 등). precache한 asset 하나라도 type이 다르면 worker의
install은 release 전체를 거절한다. 반면 페이지는 `application/octet-stream`으로 받은
font도 그대로 쓴다(리뷰 1103/06-03). install fetch는 redirect도 모두 거절한다. 그래서
호스트가 redirect를 거친 뒤에야 답하는 asset은 최종 응답이 올바른 200이어도 실패한다
(리뷰 1105/06-02). 이 asset 검사는 worker가 없는 빌드에서도 돈다. `nosniff`에서는 type이
다른 script나 style이 어차피 페이지를 깬다. 또 나중에 worker를 켜는 release가 새 hosting
검사를 받지 않아도 된다. type이 다른 font나 image는 worker 없는 페이지에서는 그래도
로드되지만, 이 검사에서는 실패한다.
The served `release-manifest.json` must name the `buildId` and `releaseId` of
the release being checked: correct headers on an earlier release are not
evidence for this one (review 1101/13-01). That release is
`<release-root>/dist` with `-- --release-root <extracted archive>` (FE-GATE-019
passes the promoted archive), otherwise the local `dist`.
호스트가 내준 `release-manifest.json`은 검사하는 release의 `buildId`와 `releaseId`를
담아야 한다. 이전 release의 헤더가 맞아도 이번 release의 증거는 아니다(리뷰 1101/13-01).
검사하는 release는 `-- --release-root <extracted archive>`를 주면
`<release-root>/dist`다(FE-GATE-019는 승격한 archive를 넘긴다). 주지 않으면 로컬
`dist`다.
Those two names come from the CI run, so a release rebuilt in the same run
carries them as well. The served `config.json` must therefore equal the
release's `dist/config.json`, the document release admission (FE-GATE-027)
admitted, in every field except the two emergency switches
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` (FE-RB-001), and the served
`index.html` must name the release's entry script (review 1103/13-01).
두 이름은 CI run에서 온다. 그래서 같은 run에서 다시 빌드한 release도 같은 이름을 갖는다.
따라서 호스트가 내준 `config.json`은 release의 `dist/config.json`과 모든 칸이 같아야
한다. 이 파일은 release admission(FE-GATE-027)이 승인한 문서다. 예외는 두 긴급 스위치
`CAPABILITY_OVERRIDES`와 `FEATURE_OVERRIDES`(FE-RB-001)뿐이다. 호스트가 내준
`index.html`도 release의 진입 스크립트를 가리켜야 한다(리뷰 1103/13-01).
The probe also checks the two serving premises the bundle budget and the split
initial chunks rest on (review 1103/13-02): the entry script arrives with a
`Content-Encoding` from `hashedAsset.contentEncodings` (the budget counts gzip
bytes; uncompressed, the initial JavaScript is about three times larger), and
the TLS handshake negotiates a protocol from `transport.alpnProtocols` (`h2`;
over HTTP/1.1 the initial files queue for six connections). A host that cannot
meet them fails FE-GATE-019; a product that has to serve that way changes the
declaration in `config/hosting/cache-policy.json` in the same change that
groups its initial chunks ("초기 청크 수와 HTTP/1.1" in
[`performance-evidence.md`](performance-evidence.md)).
probe는 번들 예산과 나뉜 초기 chunk가 기대는 두 가지 전송 전제도 검사한다(리뷰
1103/13-02). 첫째, 진입 스크립트가 `hashedAsset.contentEncodings`에 있는
`Content-Encoding`으로 온다. 예산은 gzip 바이트를 센다. 압축하지 않으면 초기
JavaScript는 약 세 배 크다. 둘째, TLS handshake가 `transport.alpnProtocols`에 있는
프로토콜(`h2`)을 맺는다. HTTP/1.1에서는 초기 파일이 연결 여섯 개를 기다리며 줄을 선다.
이 전제를 지키지 못하는 호스트는 FE-GATE-019에서 실패한다. 그렇게 내보낼 수밖에 없는
제품은 초기 chunk를 묶는 변경에서 `config/hosting/cache-policy.json`의 선언도 함께
바꾼다([`performance-evidence.md`](performance-evidence.md)의 "초기 청크 수와 HTTP/1.1").
FE-GATE-019 is therefore a production-stage gate (`production_gate` job,
`PROD_PROMOTION_READY`). It runs after `promotion` and after the `deployment`
job. That job is the project's deployment slot and is empty in this
repository: uploading the release, switching the active pointer, and the
post-switch smoke are the project's provider adapter, chosen with the hosting
provider. While the slot is empty FE-GATE-019 does not probe the host and ends
`UNVERIFIED`. How to fill it is in
[`ci-quality-gates.md`](ci-quality-gates.md) (review 1101/13-01).
그래서 FE-GATE-019는 production 단계 gate다(`production_gate` job,
`PROD_PROMOTION_READY`). 이 gate는 `promotion` 뒤, 그리고 `deployment` job 뒤에 돈다.
그 job은 프로젝트의 배포 슬롯이고, 이 repo에서는 비어 있다. release 업로드,
활성 포인터 전환, 전환 뒤 smoke는 프로젝트의 provider adapter가 맡는다. 이 adapter는
hosting provider를 고를 때 함께 정한다. 슬롯이 비어 있는 동안 FE-GATE-019는 호스트를
probe하지 않고 `UNVERIFIED`로 끝난다. 슬롯을 채우는 방법은
[`ci-quality-gates.md`](ci-quality-gates.md)에 있다(리뷰 1101/13-01).
Keep a retired release's hashed assets reachable while any open tab may still
request them. The minimum is the previous release while the next one is
active (the rolling window modeled in `tests/release/release-fixture.ts`).
Size it to the longest session the product supports; a tab older than that
depends on the reload-once recovery (FE-RB-002).
내린 release의 hashed asset은 열린 탭이 아직 요청할 수 있는 동안 닿을 수 있게 둔다.
최소한 다음 release가 활성인 동안 이전 release 하나는 남긴다
(`tests/release/release-fixture.ts`가 모형으로 만든 rolling window). 보관 기간은 제품이
지원하는 가장 긴 세션에 맞춘다. 그보다 오래된 탭은 한 번 새로 고치는 복구(FE-RB-002)에
기댄다.
## 운영 환경이 지켜야 할 조건
@@ -180,7 +168,7 @@ depends on the reload-once recovery (FE-RB-002).
`Cache-Control: no-cache`, JavaScript `Content-Type`으로 준다. — FE-GATE-019가 잰다
(`surfaces.serviceWorker`).
15. 빌드가 worker를 싣지 않으면 `/service-worker.js`는 404로 답한다. SPA fallback이
`index.html`로 대신 답하지 않는다(아래 「Service Worker steps」 4). — 아무도 재지 않는다.
`index.html`로 대신 답하지 않는다(아래 「Service Worker 절차」 4). — 아무도 재지 않는다.
worker가 없는 빌드에서는 probe가 이 경로를 요청하지 않는다.
16. 소스맵을 공개하지 않는다. — release의 `dist`에 `.map`이 없는지는 FE-GATE-019가
잰다(`surfaces.sourceMap`). 호스트가 `.map` 요청을 404로 막는지는 아무도 재지 않는다.
@@ -200,45 +188,43 @@ depends on the reload-once recovery (FE-RB-002).
되돌릴 release의 묶음과 파일은 바꾸기 전에 `drill:runbook -- FE-RB-005`가 확인한다.
호스트에서 바꾼 결과는 아무도 재지 않는다. 그 drill은 `UNVERIFIED`로 끝난다(위 단락).
## Service Worker steps (only when the static selection is not `null`)
## Service Worker 절차 (정적 선택이 `null`이 아닐 때만)
The worker is part of the release tuple: `service-worker.js` comes from the
same build as the HTML and assets it caches.
worker는 release 묶음의 일부다. `service-worker.js`는 그것이 캐시하는 HTML, asset과 같은
빌드에서 나온다.
1. **Rollback N+1 → N.** Switching the tuple serves N's `service-worker.js`.
The browser's update check installs it; the worker never calls
`skipWaiting()` on install (`src/adapters/service-worker/service-worker-entry.ts`),
so it waits until every tab of the scope closes or a page calls
`requestActivation()`. The template has no page that calls it. The cache
name is the asset-set digest, so if N's cache is still there as the
retained previous cache, the install reuses it and never deletes it on
failure (`service-worker-static-assets.ts` `installStaticAssets`). Tabs still on N+1 keep worker N+1, so N+1's assets
stay reachable for the rolling window above. Only activation deletes owned
caches (current plus the highest-marked previous one). While a worker
waits, every release that replaces the waiting worker leaves its cache
behind, so a scope holds one precache per release until its tabs close
(review 1103/06-04; `docs/operations/browser-file-storage-recovery.md` §8).
2. **Turn the worker off without a rebuild.** Set
`CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"` in the runtime config. The
next boot unregisters the owned registration and registers nothing; owned
caches stay (`src/contracts/runtime-capabilities.ts`
`resolveRuntimeCapabilities`, `service-worker-page-controller.ts` `start()`).
This needs a page that boots. Edit a copy and check it with
`check:release-admission --config <copy> --original <deployed>` before it
replaces the served file (`docs/runbooks/FE-RB-001.md`).
3. **A worker stops the page from booting.** Deploy a release whose static
selection is `REMOVE_REGISTRATION`. It ships a self-unregistering
`service-worker.js` (`scripts/build-frontend.ts`,
`scripts/lib/self-unregistering-service-worker.ts`): the update check
installs it over the broken worker, it skips waiting, unregisters on
activation and answers no fetch. The next load is uncontrolled
(`tests/e2e/service-worker-recovery.spec.ts`). Runbook:
1. **롤백 N+1 → N.** 묶음을 바꾸면 N의 `service-worker.js`를 내보낸다. 브라우저의
업데이트 검사가 그것을 설치한다. worker는 install 때 `skipWaiting()`을 부르지 않는다
(`src/adapters/service-worker/service-worker-entry.ts`). 그래서 scope의 모든 탭이
닫히거나 페이지가 `requestActivation()`을 부를 때까지 기다린다. 템플릿에는 그것을
부르는 페이지가 없다. 캐시 이름은 asset 묶음의 digest다. 그래서 N의 캐시가 남겨 둔
이전 캐시로 아직 있으면 install은 그것을 다시 쓰고, 실패해도 지우지 않는다
(`service-worker-static-assets.ts` `installStaticAssets`). 아직 N+1에 있는 탭은
worker N+1을 유지한다. 그래서 N+1의 asset은 위의 rolling window 동안 닿을 수 있다.
owned cache를 지우는 것은 activation뿐이다. activation은 현재 캐시와 가장 높게 표시된
이전 캐시 하나를 남긴다. worker가 기다리는 동안에는 기다리는 worker를 바꾸는
release마다 자기 캐시를 남긴다. 그래서 scope의 탭이 닫힐 때까지 release마다 precache가
하나씩 쌓인다(리뷰 1103/06-04; `docs/operations/browser-file-storage-recovery.md` §8).
2. **다시 빌드하지 않고 worker 끄기.** runtime config에
`CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"`를 넣는다. 다음 boot는 owned
registration을 해제하고 아무것도 등록하지 않는다. owned cache는 남는다
(`src/contracts/runtime-capabilities.ts` `resolveRuntimeCapabilities`,
`service-worker-page-controller.ts` `start()`). 이 방법은 페이지가 boot할 수 있어야
쓴다. 사본을 고치고, 호스트가 내주는 파일을 바꾸기 전에
`check:release-admission --config <copy> --original <deployed>`로 검사한다
(`docs/runbooks/FE-RB-001.md`).
3. **worker 때문에 페이지가 boot하지 못할 때.** 정적 선택이 `REMOVE_REGISTRATION`인
release를 배포한다. 이 release는 스스로 등록을 해제하는 `service-worker.js`를 싣는다
(`scripts/build-frontend.ts`, `scripts/lib/self-unregistering-service-worker.ts`).
업데이트 검사가 그것을 고장 난 worker 위에 설치한다. 그 worker는 대기하지 않고(skip
waiting), activation 때 등록을 해제하며, 어떤 fetch에도 답하지 않는다. 다음 로드는
worker의 제어를 받지 않는다(`tests/e2e/service-worker-recovery.spec.ts`). runbook:
`docs/operations/browser-file-storage-recovery.md` §8.
4. **Removing the worker** takes three releases:
`REMOVE_REGISTRATION` → `PURGE_OWNED_RESOURCES` (deletes owned caches) →
`null` (`src/contracts/service-worker.ts` `InstalledServiceWorkerSelection`).
Only the `REMOVE_REGISTRATION` release ships the self-unregistering
`service-worker.js`. Keep it deployed for at least the longest time a user
may stay away. A later release has no worker file, so the update check
fails with 404: on `PURGE_OWNED_RESOURCES` only a page that boots
unregisters the old worker, and on `null` nothing does (review 0929/06-06).
4. **worker 제거**는 release 세 번이 걸린다.
`REMOVE_REGISTRATION` → `PURGE_OWNED_RESOURCES`(owned cache 삭제) →
`null`(`src/contracts/service-worker.ts` `InstalledServiceWorkerSelection`).
스스로 등록을 해제하는 `service-worker.js`는 `REMOVE_REGISTRATION` release만 싣는다.
이 release는 사용자가 가장 오래 접속하지 않을 수 있는 기간 이상 배포해 둔다. 그 뒤
release에는 worker 파일이 없어서 업데이트 검사가 404로 실패한다.
`PURGE_OWNED_RESOURCES`에서는 boot하는 페이지만 옛 worker 등록을 해제하고, `null`에서는
아무것도 해제하지 않는다(리뷰 0929/06-06).
+8 -3
View File
@@ -33,13 +33,18 @@ const LEDGER_PATH = "docs/operations/adapter-remediation-ledger.md";
* `SW-01` — so rows are matched inside this pass's section rather than anywhere
* in the document.
*/
const SECTION_HEADING = "## Third re-review (2026-08-14)";
const SECTION_HEADING = "## 세 번째 재검토 (2026-08-14)";
const CLOSED_DISPOSITIONS: ReadonlySet<string> = new Set(["FIXED"]);
const RECIPES_PATH = "config/recipes/frontend-capability-recipes.json";
/** The table is `| id | prior verdict | disposition | evidence |`. */
const DISPOSITION_OFFSET_FROM_ID = 2;
/** Sentences that assert everything is done, and therefore need proof. */
const BLANKET_CLOSURE = /All\s+(?:\d+|findings|rows)[^.\n]*\b(?:FIXED|closed)\b/giu;
/**
* Sentences that assert everything is done, and therefore need proof.
* The ledger is written in Korean now, so Korean branches catch the same
* claim ("발견 38건은 … 모두 `FIXED`다"); the English branch still catches quotes.
*/
const BLANKET_CLOSURE =
/All\s+(?:\d+|findings|rows)[^.\n]*\b(?:FIXED|closed)\b|(?:모든|전체)\s*(?:발견|행)[^.\n]*(?:FIXED|닫)|(?:\d+\s*건|발견|(?<![가-힣])행)[^.\n]*(?:모두|전부)[^.\n]*(?:FIXED|닫)/giu;
async function main(): Promise<void> {
const problems: string[] = [];
-3
View File
@@ -9,8 +9,6 @@
language docs/accessibility/manual-checklist.md
language docs/contracts/compatibility.md
language docs/operations/adapter-remediation-ledger.md
language docs/operations/release-cache-rollback.md
language docs/runbooks/FE-RB-001.md
language docs/runbooks/FE-RB-002.md
language docs/runbooks/FE-RB-003.md
@@ -21,7 +19,6 @@ language docs/security/supply-chain.md
language docs/styling/design-tokens.md
language docs/testing/taxonomy.md
language src/adapters/browser-transfer/image-cdn/README.md
number docs/operations/ci-quality-gates.md 4.4.3
style PRODUCT.md - **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람입니다. 기본 화면(홈, 플랫폼 구성)과 Storyboo
style PRODUCT.md - **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로
style PRODUCT.md - 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → c
-3
View File
@@ -62,8 +62,6 @@ export const EXCEPTIONS_FILE = "scripts/docs-system-exceptions.txt";
export const FROZEN: ReadonlySet<string> = new Set<string>([
"cd62292c1faf9312",
"0ea431405727b1ba",
"29d6b489d280d464",
"f0eed09117035063",
"f6c533a3450c74be",
"b76f8449ca6ad18b",
"61a22114f0f80622",
@@ -74,7 +72,6 @@ export const FROZEN: ReadonlySet<string> = new Set<string>([
"07db060102714081",
"a42bc30fb525d6c9",
"59569b9b066cffcc",
"33ba6f03c95bd8e7",
"dce0f0c48d3876a4",
"e1e286fae81074d4",
"4495c81b34b2ccc9",